TypeScript nodenext模式下如何解决tsx导入的类型与构建冲突

该问题是TypeScript ESM规则与Docusaurus构建解析逻辑不匹配导致的：

• 当tsconfig.json中moduleResolution设为node16/nodenext时，TypeScript严格遵循Node.js ESM规范，要求相对导入必须显式声明运行时的文件扩展名，同时禁止导入路径直接使用.ts/.tsx这类TS源文件后缀，要求写编译后产出的.js后缀
• Docusaurus底层基于Webpack/Rspack构建，默认解析逻辑会优先匹配无后缀、.ts/.tsx后缀的源文件，不会自动将.js后缀的导入请求映射到同名TS源文件，因此写.js后缀会触发构建找不到文件的错误

方案1：使用TS专门为打包工具设计的bundler模块解析模式（最简便） #

该方案无需修改Docusaurus构建配置，从TS侧适配打包工具的解析逻辑：

1. 打开项目根目录的tsconfig.json
2. 将compilerOptions下的moduleResolution字段值从node16/nodenext改为bundler

{
  "compilerOptions": {
    // 其他已有配置...
    "moduleResolution": "bundler"
  }
}

说明：bundler是TypeScript 5.0+版本推出的解析模式，完整支持package.json中exports/imports字段解析，完全覆盖你之前配置node16要解决的自定义包导入识别需求，不会回退已经修好的路径识别能力，同时不会强制要求导入路径写扩展名，和Docusaurus等前端打包工具的解析逻辑完全对齐。

3. 重启IDE的TS服务即可消除警告，动态导入直接写无后缀的文件路径即可（注意相对路径需补全开头的./），可同时通过TS检查和Docusaurus构建。

方案2：调整Docusaurus构建解析规则，适配TS的node16/nodenext要求 #

如果必须使用node16/nodenext模块解析（比如项目同时要跑Node侧的ESM脚本），可以修改Docusaurus的Webpack解析配置，让构建时自动将.js后缀的请求映射到同名TS源文件：

1. 打开项目根目录的docusaurus.config.ts（或.js配置文件）
2. 在配置中添加Webpack自定义解析规则，优先匹配.ts/.tsx后缀：

export default {
  // 保留原有其他配置...
  webpack: {
    configure: (webpackConfig) => {
      // 将.ts/.tsx后缀放到解析优先级最前面
      webpackConfig.resolve.extensions.unshift('.tsx', '.ts');
      return webpackConfig;
    }
  }
}

3. 重启开发服务、重启TS服务后，动态导入按照TS提示写.js后缀即可同时通过类型检查和构建流程。

不推荐的临时方案 #

如果需要快速绕过检查，可以在对应导入行上方添加// @ts-expect-error注释压制TS报错，但该方式会跳过对应行的类型校验，容易遗漏真实的路径书写错误，仅适合临时调试使用，不建议在生产代码中长期保留。

配置修改完成后按以下步骤校验效果：

• 在VS Code中通过命令面板执行TypeScript: Restart TS Server重启TS服务，确认类型警告消失
• 执行npm run build验证Docusaurus构建流程正常，无文件找不到的错误

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