tsc默认导入jsbi@3.2.5时错误推断多余.default包装问题

核心原因 #

jsbi@3.2.5的类型声明与TypeScript NodeNext/Node16模块解析模式下的ESM-CJS交互规则不匹配，导致类型推断和运行时行为矛盾：

1. jsbi包的类型与模块结构不兼容

   • jsbi未在package.json中设置type: module，默认被识别为CJS包，但它的类型声明文件jsbi.d.ts采用了ESM风格的export default class JSBI写法。
   • 实际上jsbi的CJS入口文件是直接将module.exports赋值为JSBI类，而非导出包含default属性的对象。

2. NodeNext模块解析的严格规则
   在NodeNext模式下，TS会严格遵循Node.js的ESM导入CJS逻辑：对于无type: module的CJS包，TS会将ESM风格的export default类型声明解析为「CJS模块的module.exports是一个包含default属性的对象」，而非直接导出JSBI类。这就导致TS错误要求你使用JSBI.default.BigInt，但运行时该写法会返回undefined，直接调用JSBI.BigInt才是正确的。

3. bundler模式的兼容性处理
   切换到moduleResolution: bundler后，TS采用打包工具（如Webpack、Vite）的宽松解析规则，会自动抹平CJS/ESM默认导出的差异，正确推断JSBI就是类本身，因此报错消失。

解决方案 #

方案1：使用bundler模块解析（推荐） #

如果项目最终通过打包工具构建，保持moduleResolution: bundler是最简单的方案，打包工具会自动处理模块兼容问题。

方案2：适配TS推断的导入方式（临时方案） #

若必须使用NodeNext模式，可改用命名空间导入并手动取default：

import * as JSBI from 'jsbi';
// 同时兼容TS类型推断与运行时逻辑
console.log(JSBI.default.BigInt(1));

此写法仅为适配TS的错误推断，不符合运行时实际逻辑，不推荐长期使用。

方案3：升级jsbi版本 #

检查jsbi后续版本是否修复了类型声明问题（比如添加typesVersions区分CJS/ESM类型，或修改CJS类型声明为export = JSBI），升级到修复后的版本即可彻底解决问题。

内容的提问来源于stack exchange，提问作者bittervec