TypeScript Monorepo中如何使用包专属TypeScript路径？

问题背景 #

你的项目结构里，前端通过workspace直接导入后端代码实现tRPC路由类型同步，后端用TypeScript的paths配置了@utils/*这类别名来简化路径。用Vite开发时一切正常，但在前端目录执行tsc做类型检查时，会出现Cannot find module '@utils/x' or its corresponding type declarations的错误。

问题根源 #

你猜的方向完全正确：tsc在前端目录运行时，只会加载当前目录的tsconfig.json，不会自动读取后端目录里的tsconfig配置。后端代码里用的@utils/*这类别名，在前端的tsconfig里没有对应的映射规则，所以tsc无法解析这些别名路径。

可行解决方案 #

方案1：前端tsconfig同步后端的paths映射 #

直接在前端的tsconfig.json的compilerOptions.paths里添加后端别名的映射，注意要基于前端目录的相对路径来写：

{
  "compilerOptions": {
    // 前端原有配置
    "baseUrl": "./",
    "paths": {
      // 前端自己的别名，建议加前缀避免冲突
      "@frontend/utils/*": ["src/utils/*"],
      // 后端别名的映射，路径指向后端src目录
      "@utils/*": ["../../services/backend/src/utils/*"],
      "@routes/*": ["../../services/backend/src/routes/*"]
    }
  }
}

这种方式简单直接，但如果后端的paths配置有变动，前端也要同步更新，维护成本会高一点。另外一定要注意别名冲突，所以前端自己的别名最好加上独特前缀（比如@frontend/），避免和后端别名重名。

方案2：使用TypeScript项目引用（Project References） #

这是更规范的解决方案，能让tsc自动识别后端的tsconfig配置，同时保持前后端各自配置的独立性：

1. 修改后端tsconfig.json：启用composite模式（必须开启才能被其他项目引用）：

{
  "compilerOptions": {
    "composite": true,
    "declaration": true, // 可选，但建议开启，生成类型声明文件
    "paths": { /* 后端原有paths配置 */ }
  },
  "include": ["src/**/*"]
}

2. 修改前端tsconfig.json：添加对后端项目的引用，并包含后端代码目录：

{
  "compilerOptions": { /* 前端原有配置 */ },
  "references": [
    { "path": "../../services/backend" } // 指向后端目录的tsconfig
  ],
  "include": ["src/**/*", "../../services/backend/src/**/*"]
}

3. 执行类型检查：用tsc --build命令替代直接tsc，这个命令会先处理后端项目的类型，再处理前端，后端的别名就能被正确解析了。

方案3：后端改用相对路径（不推荐） #

如果不想修改tsconfig，可以把后端代码里的别名替换成相对路径，但这会破坏后端原本简洁的路径结构，后期维护起来很麻烦，所以只作为临时应急方案。

总结 #

优先推荐使用项目引用的方案，既能保持前后端配置独立，又能让tsc正确识别后端的别名规则；如果项目结构简单，也可以选择同步paths映射的方式快速解决问题。

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