在新项目中使用自有库遇ESM模块解析失败问题求助

问题背景 #

给自有库owned-lib的package.json添加"type": "module"配置后，在新项目new-project中引入该库时出现大量模块解析错误，错误日志提示无法解析@company-name/another-owned-lib/dist，原因是严格EcmaScript Module（ESM）模式要求所有导入必须添加完整文件扩展名。

涉及三个仓库：

• new-project：正在开发的新项目
• owned-lib：已更新为ESM的自有库
• another-owned-lib：未修改的自有库，同时被前两者依赖，且自身也配置了"type": "module"

错误原因 #

1. ESM规范强制要求：启用"type": "module"后，Node.js和打包器会严格校验导入语句，必须包含完整文件扩展名（如.js），不能像CommonJS那样省略。
2. 编译产物不规范：owned-lib或another-owned-lib的编译输出中，存在省略扩展名的导入语句，导致new-project的webpack打包器无法解析。
3. TS版本与配置差异：owned-lib使用TypeScript 5.x，new-project使用4.x，部分ESM相关解析逻辑存在兼容性问题。

解决方案 #

1. 修复another-owned-lib的编译配置 #

因为another-owned-lib也是ESM模块，必须确保其编译产物符合规范：

• 修改another-owned-lib的tsconfig.json，调整模块解析规则：

  {
    "compilerOptions": {
      "module": "esnext",
      "moduleResolution": "bundler", // 或"node16"，严格遵循ESM解析逻辑
      "target": "esnext",
      "outDir": "dist",
      "declaration": true
      // 保留原有其他配置
    }
  }
  

• 重新编译another-owned-lib，检查dist目录下的JS文件，确认所有导入语句都带有.js扩展名（比如import { utils } from './utils.js'，而非import { utils } from './utils'）。

2. 调整owned-lib的编译与发布配置 #

• 同步owned-lib的TS配置，确保编译产物带完整扩展名：
  将tsconfig.json中的moduleResolution改为"bundler"或"node16"，重新编译。
• 确认owned-lib的package.json入口配置正确：

  "main": "dist/index.js", // 必须带.js扩展名
  "type": "module",
  "types": "dist/index.d.ts"
  

3. 适配new-project的配置 #

• 优先升级TypeScript版本：将new-project的TS版本升级至5.x，对齐owned-lib的版本，避免兼容性问题：

  npm install typescript@^5.x.x --save-dev
  

• 若无法升级TS，修改new-project的tsconfig.json以兼容ESM：

  {
    "compilerOptions": {
      "module": "esnext",
      "moduleResolution": "bundler", // 替换原有的"node"配置
      "target": "esnext", // 提升目标版本，更好支持ESM
      // 保留原有其他配置
    }
  }
  

• 若使用react-scripts 5仍有问题，可通过craco修改webpack配置：
  安装craco后，创建craco.config.js：

  module.exports = {
    webpack: {
      configure: (config) => {
        config.resolve.extensions.push('.js', '.jsx', '.ts', '.tsx');
        return config;
      },
    },
  };
  

  然后修改package.json的启动脚本为craco start、craco build。

4. 重置依赖验证 #

删除new-project的node_modules和锁文件，重新安装依赖，确保所有配置生效：

rm -rf node_modules package-lock.json
npm install

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