TypeScript项目切换ESM后默认导入模块类型报错求助

问题根源 #

这类问题基本都是因为CommonJS模块的类型定义没跟上ESM的导入逻辑，或者TypeScript在ESM模式下解析CommonJS模块时，类型检查和实际运行时的行为不匹配——所以代码能正常运行，但编辑器会报类型错误。

具体解决办法 #

1. 更新类型定义或模块本身 #

先试试更新对应模块的类型包（如果依赖第三方类型）：

npm install @types/wait @types/aedes @types/mqemitter --save-dev

像ajv这种自带类型的模块，直接升级到最新版本即可：

npm install ajv@latest

很多时候旧版本的类型定义未适配ESM规范，更新后就能解决问题。

2. 调整tsconfig的模块解析配置 #

在tsconfig.json中添加或修改以下配置，让TypeScript更好地兼容CommonJS模块的ESM导入逻辑：

{
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "Node16",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

• allowSyntheticDefaultImports：让TypeScript为没有默认导出的CommonJS模块生成虚拟默认导出类型，匹配运行时的实际行为。
• esModuleInterop：配合上面的配置，抹平ESM与CommonJS导入的差异。
• skipLibCheck：跳过第三方类型定义的语法检查，避免旧类型包的错误干扰。

3. 单个模块的临时类型断言 #

如果某个模块仍报错，无需写全局模块声明，直接用类型断言绕开类型检查，不影响代码运行：

import wait from 'wait';
// 手动指定类型，适配实际调用逻辑
const waitFn = wait as unknown as (ms: number) => Promise<void>;
await waitFn(1000);

4. 确认模块实际导出结构 #

实在无法解决时，打印模块内容查看实际导出结构：

import * as wait from 'wait';
console.log(wait);

根据打印结果调整导入方式，比如如果实际导出是wait.default但类型定义未标注，就针对性调整——不过这种情况较少见，大多还是类型定义的问题。

5. 规范导入习惯 #

ESM模式下记得导入要加完整文件后缀（比如.js），不要混用require和import，避免模块解析逻辑混乱。

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