如何在NPM发布TypeScript模块时避免导入路径含dist

我太懂这种烦恼了！之前发布TS库的时候也踩过这个坑，明明编译产物在dist里，但用户导入非要加个dist层级，显得特别不专业。其实只要调整几个关键配置，就能让导入路径变得干净利落。

核心思路 #

本质是告诉NPM：你的库的主入口文件、类型定义文件以及各个子模块的位置都在dist目录里，这样用户导入时就不需要手动指定dist了。

步骤1：修改package.json的关键配置 #

打开你的package.json，添加/修改以下字段：

{
  // 主入口（适配CommonJS模块环境）
  "main": "dist/index.js",
  // ES模块入口（适配现代前端项目如Angular）
  "module": "dist/index.esm.js",
  // 类型定义文件入口，让TypeScript能识别类型
  "types": "dist/index.d.ts",
  // 定义子模块的导入路径（关键！支持<库名>/Component这种简洁导入）
  "exports": {
    ".": "./dist/index.js",
    "./Component": "./dist/Component.js"
  },
  // 指定要发布到NPM的文件（只传必要内容，避免把源文件lib上传）
  "files": [
    "dist/**/*",
    "README.md",
    "LICENSE",
    "CHANGELOG.md"
  ]
}

• 如果你的库是单入口（所有导出都集中在lib/index.ts），那exports里只留".": "./dist/index.js"就行，用户直接import {xxx} from '<库名>'即可。
• 如果是多文件独立导出（比如每个组件单独一个文件），就把每个子模块都加到exports里，像上面的./Component对应dist/Component.js。

步骤2：调整tsconfig.json确保编译结构正确 #

你的tsconfig.json需要保证编译后的文件结构和lib目录一致，并且类型文件和JS文件放在一起：

{
  "compilerOptions": {
    "outDir": "./dist",          // 编译产物输出到dist目录
    "rootDir": "./lib",          // 源文件根目录设为lib，保证dist内的文件结构和lib完全一致
    "declaration": true,         // 自动生成类型定义文件.d.ts
    "declarationDir": "./dist",  // 类型文件和JS文件放在同一目录，方便TypeScript识别
    "module": "ESNext",          // 可选CommonJS，根据你的库定位选择
    "target": "ES2020",
    "strict": true
  },
  "include": ["lib/**/*"],       // 只编译lib目录下的源文件
  "exclude": ["node_modules", "dist"]
}

步骤3：本地验证（避免发布后踩坑） #

发布前一定要本地测试，确保配置生效：

1. 执行npm run build编译你的库
2. 运行npm pack生成一个本地的tar包（比如your-library-1.0.0.tgz）
3. 在你的Angular测试项目里执行npm install ../path/to/your-library-1.0.0.tgz
4. 尝试导入：import {Component} from '<库名>'或者import {Component} from '<库名>/Component'，看是否能正常识别类型并运行

最后发布 #

确认测试没问题后，就可以正常执行npm publish了。现在用户导入你的库时，完全不需要带dist层级，和使用其他第三方库的体验一致！

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