Yarn Workspace Monorepo构建common包后app出现模块找不到错误

我有一个采用Yarn Workspace与TypeScript的Monorepo项目，目录结构如下：

packages
--- common
------ src
------ package.json
------ tsconfig.json
--- app
------ src
------ package.json
------ tsconfig.json
package.json
tsconfig.json

执行yarn build或yarn workspace @project/common build构建common包后，app无法识别@project/common模块，TypeScript在所有导入处抛出错误：
Cannot find module '@project/common' or its corresponding type declarations.
只有重启VSCode窗口或重新加载TypeScript项目才能消除这个语法错误。请问哪里配置错了？

环境信息 #

• TypeScript: 5.4.2
• Yarn: 4.1.0
• Node: 18.x

相关配置文件 #

根目录package.json #

{
  "name": "@project/project",
  "version": "1.0.0",
  "private": true,
  "engines": {
    "node": "18.x"
  },
  "workspaces": {
    "packages": [
      "packages/*"
    ]
  },
  "installConfig": {
    "hoistingLimits": "dependencies"
  },
  "scripts": {
      // ...scripts
  },
  "devDependencies": {
      // ...dev dependencies
  },
  "packageManager": "yarn@4.1.0"
}

根目录tsconfig.json #

{
  "compilerOptions": {
    "allowJs": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "sourceMap": true,
    "declaration": true,
    "strict": true,
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false,
    "ignoreDeprecations": "5.0",
    "removeComments": true,
    "allowUnreachableCode": false
  }
}

packages/common/package.json #

{
  "name": "@project/common",
  "private": true,
  "version": "1.0.0",
  "main": "build/index.js",
  "types": "build/index.d.ts",
  "engines": {
    "node": "18.x"
  },
  "scripts": {
    "build": "rm -rf ./build && tsc -p ."
  },
  "dependencies": {
    // ...dependencies
  },
  "devDependencies": {
    // ...dev dependencies
  }
}

packages/app/package.json #

{
  "name": "@project/app",
  "private": true,
  "version": "1.0.0",
  "engines": {
    "node": "18.x"
  },
  "scripts": {
    // ...scripts
  },
  "dependencies": {
    "@project/common": "*",
    // ...dependencies
  },
  "devDependencies": {
    // ...dev dependencies
  }
}

核心原因 #

构建common包时直接删除整个build目录，导致TypeScript语言服务丢失了之前识别的类型文件路径；新的build目录生成后，TypeScript语言服务没有自动重新扫描路径，因此抛出找不到模块的错误。

具体修复步骤 #

1. 调整common包的构建脚本
   不要删除整个build目录，仅清理目录内的文件，保留目录结构，避免TypeScript丢失路径引用：
   修改packages/common/package.json中的build脚本：

   "scripts": {
     "build": "rm -rf ./build/* && tsc -p ."
   }
   

   若使用rimraf工具，可改为更安全的写法：

   "scripts": {
     "build": "rimraf ./build/**/* && tsc -p ."
   }
   

2. 配置TypeScript路径映射与项目引用
   在根目录tsconfig.json中添加路径映射和项目依赖声明，让TypeScript明确模块位置：

   {
     "compilerOptions": {
       // 原有配置...
       "baseUrl": ".",
       "paths": {
         "@project/common": ["packages/common/src", "packages/common/build"]
       }
     },
     "references": [
       { "path": "./packages/common" },
       { "path": "./packages/app" }
     ]
   }
   

3. 完善子包的tsconfig配置
   在packages/common/tsconfig.json中添加继承与输出配置：

   {
     "extends": "../../tsconfig.json",
     "compilerOptions": {
       "rootDir": "./src",
       "outDir": "./build"
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "build"]
   }
   

   在packages/app/tsconfig.json中添加依赖引用：

   {
     "extends": "../../tsconfig.json",
     "compilerOptions": {
       "rootDir": "./src",
       "outDir": "./build"
     },
     "references": [{ "path": "../common" }],
     "include": ["src/**/*"],
     "exclude": ["node_modules", "build"]
   }
   

4. 调整Yarn链接模式（可选）
   若使用Yarn 4的PnP模式，可能影响TypeScript对本地包的识别，可在根目录.yarnrc.yml中切换为node_modules模式：

   nodeLinker: node-modules
   

   执行yarn install生效。

额外优化 #

在VSCode中，无需重启窗口，可通过快捷键Ctrl+Shift+P（Windows/Linux）/Cmd+Shift+P（Mac）执行TypeScript: Reload Project快速修复错误。

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