NPM Workspace Monorepo中TSC报模块未找到的问题咨询

问题根源 #

TypeScript编译器无法识别test/a这个导入路径对应的实际模块位置，大概率是包名配置不匹配、TypeScript路径映射未设置，或是Monorepo的项目引用未正确配置导致的。

具体解决方案 #

1. 核对导入路径与子包包名 #

查看packages/a/package.json中的name字段，如果实际包名是@test/a（而非test/a），直接修正导入语句：

// 原错误导入
import { A } from "test/a";
// 修正为匹配包名的导入
import { A } from "@test/a";

2. 配置TypeScript路径映射（自定义短路径） #

如果想保留test/a这类自定义短路径导入，在根目录的tsconfig.json中添加baseUrl和paths配置，告诉编译器路径对应关系：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "test/a": ["packages/a/src/index.ts"],
      "test/common": ["packages/common/src/index.ts"]
    }
  },
  "include": ["packages/**/*"]
}

3. 启用TypeScript项目引用（推荐） #

对于NPM Monorepo，使用TypeScript的Project References能确保依赖包的类型正确传递，且编译顺序符合依赖关系：

• 在每个子包的tsconfig.json中添加composite和references配置（以依赖a包的common包为例）：

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  },
  "references": [
    { "path": "../a" }
  ],
  "include": ["src/**/*"]
}

• 在根目录的tsconfig.json中添加项目引用：

{
  "references": [
    { "path": "./packages/a" },
    { "path": "./packages/common" }
  ]
}

• 用tsc -b命令替代tsc执行编译，该命令会自动处理依赖顺序并构建所有关联项目。

4. 确保子包的类型入口配置正确 #

每个子包的package.json需要指定types字段，指向编译后的类型声明文件，让TypeScript能找到类型定义：

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

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