pnpm私有TypeScript工作区：暴露src还是dist？如何优化开发体验？

直接将私有库的main指向src/index.ts会带来几个明确的问题：

• 多TS版本解析不一致：不同子项目用不同TS版本（比如4.7 vs 4.9）时，语法支持、类型推导规则会有差异。比如4.9新增的satisfies运算符在4.7里会直接报错；严格模式配置不同时，同一个源码在不同项目里的类型检查结果也会不一样，增加排查成本。
• 编译性能浪费：每个依赖该库的子项目都会重新编译一遍源码，而非复用预编译的dist，项目数量多的话，整体编译时间会显著增加。
• 代码边界模糊：src目录可能包含测试文件、未完成的草稿代码，即便files指定了src，如果子项目的TS配置没做排除，可能会意外引入这些非生产代码。
• 类型提示不稳定：源码的类型是实时推导的，不同TS版本或配置下，推导的类型可能有差异，导致IDE的类型提示不一致，影响开发体验。

确实会导致源码解析行为不一致。TS的语法和类型系统在 minor 版本间会有不少变化，比如4.8支持的infer增强、4.9的satisfies和类型收窄优化，这些特性在旧版本里无法识别，直接用源码会引发编译错误。此外，不同项目的tsconfig配置（如strictNullChecks、moduleResolution）差异，也会让同一个库的类型检查结果出现偏差。

推荐结合以下两种方案，兼顾开发效率和一致性：

1. 统一TS版本与基础配置

   • 在monorepo根目录安装统一的TypeScript依赖：pnpm install typescript -Dw，强制所有子项目使用根目录的TS版本。
   • 根目录创建tsconfig.base.json，定义通用的编译选项（如target、module、strict），所有子项目的tsconfig.json通过"extends": "../../tsconfig.base.json"继承，保证编译规则一致。

2. 使用TS项目引用（Project References）

   • 在每个私有库的tsconfig.json中添加"references"配置，指向依赖的其他库；同时在根目录的tsconfig.json中统一管理所有项目引用。
   • 开启增量编译：在库的tsconfig中设置"incremental": true，修改源码后TS会自动增量编译依赖该库的项目，IDE也能实时识别变更，无需手动重建。
   • 保留dist输出和原有的main、types配置，确保生产环境使用预编译代码，避免性能问题。

如果暂时不想调整工作区结构，可以用以下方式降低重建成本：

• 自动监听编译：给每个私有库添加watch脚本："scripts": { "watch": "tsc --watch" }，根目录添加统一启动脚本："scripts": { "dev:libs": "pnpm -r run watch" }，启动开发时自动监听源码变更并编译dist，IDE会自动识别dist的更新。
• IDE定向解析：在VS Code的.vscode/settings.json中配置：

  {
    "typescript.tsdk": "./node_modules/typescript/lib",
    "typescript.preferences.includePackageJsonAutoImports": "on"
  }
  

  强制IDE使用根目录的TS版本，同时优先解析工作区包的源码而非dist。
• 利用pnpm工作区链接：确保pnpm install后，子项目node_modules中的私有库是软链接到源码目录的，pnpm默认会处理这一点，IDE能直接访问源码并实时更新类型提示。

完全不需要接受“修改后必须手动重建”的现状。通过统一TS版本+项目引用的方案，既能实现开发时的实时更新，又能避免直接暴露源码的弊端；如果暂时无法调整结构，自动监听编译+IDE优化也能大幅降低开发摩擦。

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