使用ESM时TypeScript编译报错问题求助

报错汇总 #

1. 类型不存在属性错误 #

src/index.ts:6:13 - error TS2339: Property 'click' does not exist on type 'typeof import("/Users/111122223333/Projects/ts-issue/node_modules/@testing-library/user-event/dist/types/index")'.

6   userEvent.click(screen.getByRole('textbox'))

2. 表达式不可调用错误 #

src/index.ts:9:15 - error TS2349: This expression is not callable.
Type 'typeof import("/Users/111122223333/Projects/ts-issue/node_modules/next/index")' has no call signatures.

9   const app = next({

3. JSX元素无构造/调用签名错误 #

src/pages/test.tsx:6:8 - error TS2604: JSX element type 'Head' does not have any construct or call signatures.

6       <Head>

src/pages/test.tsx:6:8 - error TS2786: 'Head' cannot be used as a JSX component.
  Its type 'typeof import("/Users/111122223333/Projects/ts-issue/node_modules/next/head")' is not a valid JSX element type.

6       <Head>

核心背景与疑问 #

以上错误已在示例项目中复现，运行tsc --noEmit或npm run ts:check可触发问题。目前发现给报错代码行添加default（比如userEvent.default.click、next.default({})、调整Head的导入方式）能解决问题，但按常理无需额外添加default，期望找到无需修改代码、仅通过配置调整解决问题的方案。尝试过多种编译配置组合，未解决反而引入新错误，怀疑是TypeScript配置问题但无法定位，需要相关分析与背景信息。

问题本质分析 #

这些错误核心是ES模块与CommonJS模块的导入适配冲突：

• 第三方库（如Next.js、@testing-library/user-event）可能以CommonJS格式导出，但你的TypeScript配置未正确处理模块导入的兼容性，导致TypeScript无法识别默认导出的别名，把整个模块当成了包含default属性的命名空间对象，而非可直接调用/使用的实体。

关键配置参数说明 #

1. esModuleInterop: 启用后会自动为CommonJS模块创建默认导入的包装器，允许用import next from 'next'替代import * as next from 'next'再取default，同时避免命名冲突。
2. allowSyntheticDefaultImports: 允许TypeScript接受对没有默认导出的模块使用默认导入语法，仅做类型层面的兼容，不会生成额外代码。
3. moduleResolution: 建议设置为node16或nodenext，这两个模式严格遵循Node.js的模块解析规则，能自动区分ES和CommonJS模块的导入方式。

解决方案 #

修改tsconfig.json中的相关配置：

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "node16", // 或 "nodenext"
    "module": "ESNext", // 与moduleResolution匹配，保持模块系统一致
    "target": "ESNext"
  }
}

• 确保esModuleInterop和allowSyntheticDefaultImports都设为true，这两个参数通常需要配合使用，解决CommonJS模块的默认导入识别问题。
• moduleResolution设为node16/nodenext是因为现代项目多混合使用ES和CommonJS模块，该模式能更准确地解析导入路径和导出类型。

补充检查点 #

如果配置调整后仍有问题，需排查：

• 项目中是否存在多个tsconfig.json文件（如Next.js项目可能有主配置和服务端配置），确保所有配置文件的相关参数一致。
• 第三方库的版本是否兼容，部分旧版本库的类型定义可能存在导出格式问题，尝试升级到最新稳定版。

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