发布含子模块的TypeScript NPM包：模块及类型声明查找失败

DevOps 小满

2026-7-4

发布CommonJS/ESM混合TypeScript包到NPM的问题解决

问题1：ESM构建无法自动生成.mjs扩展名

手动修改扩展名是可行的，但更推荐用TypeScript原生能力自动生成，避免手动操作出错：

修改构建脚本：在build:esm命令中添加--outFileExtension .mjs参数，让TypeScript直接输出.mjs文件：
```
"build:esm": "tsc -p tsconfig.prod.json --module ES2022 --outDir build/esm --outFileExtension .mjs"
```
验证tsconfig配置：确保tsconfig.prod.json（或继承的tsconfig.json）中compilerOptions的module为ES2022/ESNext，moduleResolution为Node16或NodeNext，这是TypeScript正确输出ESM模块的前提。

手动修改扩展名本身合法，但自动生成更可靠，能保持构建流程一致性。

问题2：子模块导入时TypeScript类型报错

报错原因是package.json的exports字段中类型映射配置错误，TypeScript无法定位子模块的类型声明文件。修正步骤如下：

更新exports中的类型映射：给每个子模块入口添加types字段，替换原来单独的./types相关配置：

"exports": {
  ".": {
    "import": "./build/esm/index.mjs",
    "require": "./build/cjs/index.js",
    "types": "./build/@types/index.d.ts"
  },
  "./*": {
    "import": "./build/esm/*.mjs",
    "require": "./build/cjs/*.js",
    "types": "./build/@types/*.d.ts"
  },
  "./mult/*": {
    "import": "./build/esm/mult/*.mjs",
    "require": "./build/cjs/mult/*.js",
    "types": "./build/@types/mult/*.d.ts"
  }
}

调整package.json的types字段：将types设为根模块的类型文件，而非整个目录：
```
"types": "build/@types/index.d.ts"
```
确认类型文件结构：确保build/@types下的文件结构和源文件完全一致（比如mult/multiply.d.ts存在），当前你的构建产物结构符合要求，保持现有build:types脚本不变即可。