发布TypeScript npm包遇ERR_MODULE_NOT_FOUND错误求解决

以下是针对你问题的具体修复步骤：

1. 完善package.json的导出配置 #

npm包的模块入口需要明确声明，尤其是ES模块。在package.json中添加或修改以下字段：

{
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsc"
  }
}

• exports字段是npm规范中定义模块入口的标准方式，优先级高于main，确保Node.js和包管理器能正确识别模块入口
• types字段指定类型声明文件的位置，保证自动补全正常工作的同时，类型能被正确识别

2. 调整tsconfig.json配置 #

修改编译选项，确保输出符合ES模块规范且避免不必要的编译范围：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2020",
    "strict": true,
    "sourceMap": true,
    "outDir": "./dist",
    "removeComments": true,
    "declaration": true,
    "declarationMap": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

• moduleResolution: "bundler"适配现代构建工具，同时兼容Node.js的ES模块解析规则
• target: "ES2020"避免使用过新的JS语法，提升运行环境兼容性
• declaration: true生成类型声明文件，确保包的类型能被正常导出
• 缩小include范围到src/**/*，避免编译根目录下的无关文件（如package.json）

3. 确保源码中导入路径带完整扩展名 #

ES模块要求导入必须使用完整的文件扩展名（如.js），修改TS源码中的导入语句：

// 错误写法
import { utils } from './utils';

// 正确写法
import { utils } from './utils.js';

TypeScript编译时会保留这个扩展名，确保Node.js运行时能正确找到模块文件。

4. 验证编译与测试 #

• 运行npm run build，检查dist目录下是否生成了对应的.js和.d.ts文件
• 在外部测试项目中通过本地安装（如npm install ../your-package-path）或npm link导入包，测试运行是否正常

如果仍使用NodeNext模块配置，需额外注意：

• 确保module和moduleResolution都设为NodeNext
• TS会根据文件扩展名区分模块类型，.ts文件编译为.js（ES模块），若需CommonJS兼容可使用.cts文件

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