TypeScript库package.json的types字段配置与多模块并行开发困惑

我太懂这种纠结了——一边要遵循TS发布规范配置types字段，一边本地并行开发时用npm link，VS Code却总跳转到编译后的.d.ts文件，完全没法舒服地调试源代码。下面给你拆解问题本质和具体解决方案：

先明确types字段的核心作用 #

没错，官方要求发布时types字段指向编译后的index.d.ts，这是为了让其他项目安装你的包时，能直接获取到正确的类型定义，这一步是发布环节的必要配置，不能改。问题出在本地开发时，npm link会让依赖项目把你的模块当成“已发布包”来处理，所以会严格遵循package.json里的types字段去加载类型文件，而不是源文件。

本地并行开发的解决方案 #

1. 用tsconfig.json的paths映射指向源文件 #

在依赖你模块的项目的tsconfig.json里，添加paths配置，把你的模块名直接映射到源文件目录：

{
  "compilerOptions": {
    // 其他配置...
    "paths": {
      "your-module-name": ["../path-to-your-module/src"]
    }
  }
}

这样VS Code的语言服务会直接解析源文件，代码导航、跳转、智能提示都会正常工作。注意：发布依赖项目前，一定要把这个配置注释或删除，避免线上环境出错。

2. 用TypeScript项目引用（Project References） #

如果你的多个模块是关联开发的（比如monorepo结构），项目引用是更优雅的方案。它能让TS在本地开发时自动识别源文件依赖，同时编译时保持正确的类型输出：

• 在你的模块的tsconfig.json里启用composite: true，并指定输出目录：

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

• 在依赖项目的tsconfig.json里添加references：

{
  "compilerOptions": {
    // 其他配置...
  },
  "references": [
    { "path": "../path-to-your-module" }
  ]
}

这样不仅代码导航会直接跳转到源文件，还能实现增量编译，提升开发效率。

3. 临时改用本地文件依赖替代npm link #

在依赖项目的package.json里，把你的模块依赖改成本地路径：

"dependencies": {
  "your-module-name": "file:../path-to-your-module"
}

然后执行npm install，TS会优先读取源文件的类型（前提是你的模块开启了declaration: true，源文件是.ts格式）。这种方式不需要改tsconfig，但发布前记得把依赖改回正常版本号。

总结 #

• 发布阶段：types字段必须指向编译后的index.d.ts，遵循TS发布规范；
• 本地并行开发：用上述任意一种方案绕开npm link的“已发布包”逻辑，让工具直接识别源文件，兼顾开发体验和发布正确性。

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