Monorepo转TypeScript遇TS6059错误：rootDir配置问题求助

你在monorepo迁移TypeScript时遇到的这个问题，其实是monorepo场景下TS编译边界配置的典型坑，我来帮你拆解原因和解决方案：

为什么会触发这个错误？ #

TS6059的本质是：TypeScript编译components包时，误把不属于它的config/globals.ts当成了当前包的源文件，但components的rootDir被设置为./src，自然无法包含其他包的文件。

出现这种情况通常有两个核心原因：

• 你的components包代码里直接用相对路径引用了config包的文件（比如import ... from '../../config/globals.ts'），TS会把这个外部文件纳入当前包的编译上下文，强制检查是否在rootDir范围内。
• 子包的tsconfig没有正确覆盖根配置的include规则，导致根配置的全局路径（比如packages/**/*）把其他包的文件也拉进了components的编译范围。

具体解决方案 #

1. 修正子包的include与exclude配置 #

打开components包的tsconfig.json，确保include只包含当前包的源文件，明确排除其他包目录：

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["src/**/*"], // 仅包含当前包的src目录
  "exclude": ["node_modules", "dist", "../../packages/config/**/*"], // 明确排除config包
  "references": [{"path": "../config"}] // 声明对config包的依赖（后续会用到）
}

2. 用Project References管理跨包依赖 #

Monorepo下推荐使用TS的Project References来明确包边界，它能让TS清楚知道各个包的编译顺序和依赖关系，不会把其他包的文件误判为当前包的源文件：

• 在根tsconfig.json中开启composite模式，并添加子包引用：

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true
  },
  "references": [
    {"path": "./packages/config"},
    {"path": "./packages/components"}
  ]
}

• 在config包的tsconfig.json中也开启composite：

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",
    "composite": true
  },
  "include": ["src/**/*"]
}

3. 用路径别名替代相对路径引用 #

避免直接用../../config/globals.ts这种易混淆的相对路径，改用路径别名让引用更清晰，同时配合Project References让TS正确识别依赖：

• 在根tsconfig.json中配置路径别名：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@serge/config/*": ["packages/config/src/*"],
      "@serge/components/*": ["packages/components/src/*"]
    }
  }
}

• 然后在components包的代码中用别名引用：

import { someGlobal } from '@serge/config/globals';

4. 验证配置生效 #

运行编译命令时，记得加上--build参数让TS处理Project References：

tsc --build

这样TS会先编译config包，再编译components包，完全不会把config的文件当成components的源文件。

总结 #

这个错误的核心是TS对包边界的误判，通过缩小include范围、启用Project References、使用路径别名这三个步骤，就能彻底解决TS6059的问题。如果还有疑问，可以检查一下各个包的package.json是否正确设置了main或exports字段，确保跨包引用的入口是正确的。

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