Node/PNPM升级后TypeScript构建输出路径异常求助

背景 #

正在将包含27个包的单仓项目从Node.js 16.x升级至18.x（后续计划升级到更高版本），同时将包管理器从PNPM 6.x升级到7.x。升级后发现TypeScript构建输出路径从原本的./dist变为./dist/lib，导致依赖该包的其他项目出现引用错误。

问题复现（以@myapp/utils包为例） #

源码目录结构 #

/common/utils
/common/utils/lib/
/common/utils/lib/uid
/common/utils/lib/uid/index.ts
/common/utils/lib/uid/uid.factory.ts

升级前（Node 16.13.0 + PNPM 6.32.2） #

执行构建命令 rimraf dist && tsc 后，输出目录结构：

/common/utils
/common/utils/dist/
/common/utils/dist/uid
/common/utils/dist/uid/index.d.ts
/common/utils/dist/uid/index.js
/common/utils/dist/uid/uid.factory.d.ts
/common/utils/dist/uid/uid.factory.js
/common/utils/dist/tsconfig.tsbuildinfo

升级后（Node 18.0.0 + PNPM 7.0.0） #

构建输出目录多了一层lib，仅tsconfig.tsbuildinfo保留在./dist下：

/common/utils
/common/utils/dist/
/common/utils/dist/lib
/common/utils/dist/lib/uid
/common/utils/dist/lib/uid/index.d.ts
/common/utils/dist/lib/uid/index.js
/common/utils/dist/lib/uid/uid.factory.d.ts
/common/utils/dist/lib/uid/uid.factory.js
/common/utils/dist/tsconfig.tsbuildinfo

此变化导致依赖@myapp/utils的包A报错：

Cannot find module '@myapp/utils' or its corresponding type declarations.

相关配置详情 #

@myapp/utils的核心配置 #

package.json（devDependencies部分）

"devDependencies": {
  "@types/node": "~20.10.5",
  "typescript": "~5.3.3"
}

tsconfig.json（compilerOptions部分）

"compilerOptions": {
    "outDir": "./dist",
    "baseUrl": "./lib"
}

包A的package.json相关配置 #

"dependencies": {
  "@myapp/utils": "workspace:0.5.0"
},
"dependenciesMeta": {
  "@myapp/utils": {
    "injected": true
  }
}

临时方案与疑问 #

临时方案A #

在包A的tsconfig.json中添加paths配置，同时修改所有导入语句增加/lib后缀。

• 疑问：是否存在无需修改所有代码和配置的更优方案？

临时方案B #

在@myapp/utils的tsconfig.json中添加rootUrl配置，修正输出路径，但导致tsconfig.tsbuildinfo移出dist目录，引发增量构建问题。

• 疑问：不满意这两种临时方案，是否有其他解决思路？

推荐解决思路 #

1. 显式配置TypeScript的rootDir #

在@myapp/utils的tsconfig.json的compilerOptions中添加rootDir字段，指定源码根目录：

"compilerOptions": {
    "outDir": "./dist",
    "baseUrl": "./lib",
    "rootDir": "./lib"
}

• 原理：TypeScript默认会自动推断源码根目录，升级后环境变化可能导致推断结果改变。显式设置rootDir为./lib，会让TypeScript将lib下的文件直接输出到outDir（即./dist），不再嵌套lib目录，同时tsconfig.tsbuildinfo会保留在./dist下，不影响增量构建。

2. 验证并修正package.json的入口字段 #

确保@myapp/utils的package.json中main、types等入口字段指向正确的输出路径：

{
  "main": "./dist/uid/index.js",
  "types": "./dist/uid/index.d.ts"
}

• 原理：依赖包会通过这些字段查找模块入口，确保路径与新的输出结构匹配，避免引用错误。

3. 检查PNPM workspace配置 #

确认项目根目录的pnpm-workspace.yaml配置正确，确保workspace内的包引用路径无误：

packages:
  - 'common/utils'
  # 其他包路径

• 原理：PNPM 7对workspace的处理逻辑有细微调整，确保配置正确可避免包引用的路径解析问题。

附录：@myapp/utils升级前后完整配置 #

升级前tsconfig.json #

{
  "compilerOptions": {
    "outDir": "./dist",
    "baseUrl": "./lib",
    // 其他原有配置
  },
  // 其他配置项
}

升级前package.json #

{
  "name": "@myapp/utils",
  "version": "0.5.0",
  "main": "./dist/uid/index.js",
  "types": "./dist/uid/index.d.ts",
  "devDependencies": {
    "@types/node": "~20.10.5",
    "typescript": "~5.3.3"
  },
  // 其他配置项
}

升级后tsconfig.json（未修改前） #

{
  "compilerOptions": {
    "outDir": "./dist",
    "baseUrl": "./lib",
    // 其他原有配置
  },
  // 其他配置项
}

升级后package.json（未修改前） #

{
  "name": "@myapp/utils",
  "version": "0.5.0",
  "main": "./dist/uid/index.js",
  "types": "./dist/uid/index.d.ts",
  "devDependencies": {
    "@types/node": "~20.10.5",
    "typescript": "~5.3.3"
  },
  // 其他配置项
}

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