React Monorepo（Yarn Workspaces+TS）跨包导入TS文件报错求助

我之前在搭建类似的Yarn Workspaces + TypeScript项目时也碰到过一模一样的错误，大概率是你的Common包或者Web包的配置遗漏了关键项，下面是几个最可能的原因和对应的解决办法：

1. Common包的package.json未正确配置入口字段 #

Yarn Workspaces通过软链接让Web包可以直接引用Common包，但如果Common包的package.json没有指定正确的编译后文件入口，Web包可能会直接尝试加载未编译的TS/TSX文件，或者加载了错误的导出格式。

你需要在workspaces/common/package.json中添加以下字段：

{
  "name": "@my-project/common", // 建议用scope命名，避免包名冲突
  "main": "dist/index.js", // CommonJS格式入口
  "module": "dist/index.esm.js", // ES模块格式入口（React项目推荐配置）
  "types": "dist/index.d.ts", // TypeScript类型定义文件入口
  "scripts": {
    "build": "tsc", // 新增TS编译命令
    "watch": "tsc --watch" // 开发时自动监听源码变化并编译
  }
}

2. Common包的TypeScript编译配置错误 #

确保workspaces/common/tsconfig.json的关键编译选项正确，比如：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext", // 与package.json的module字段格式对应
    "outDir": "./dist", // 指定编译输出目录
    "declaration": true, // 生成类型定义文件
    "declarationDir": "./dist",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"], // 确保包含所有TS/TSX源码文件
  "exclude": ["node_modules", "dist"]
}

配置完后，记得在Common包目录下运行yarn build，或者根目录运行yarn workspace @my-project/common build，确保TS文件被编译成可执行的JS文件。

3. Web包的TypeScript路径配置缺失 #

虽然Yarn Workspaces已经做了软链接，但Web包的TypeScript可能无法正确识别Common包的源码或编译路径，需要在workspaces/web/tsconfig.json中添加路径映射：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@my-project/common": ["../common/src"] // 开发时可直接指向源码，生产环境可改为"../common/dist"
    },
    "esModuleInterop": true, // 关键：解决ES模块与CommonJS模块的互操作问题
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "NodeNext" // 让TS正确解析package.json中的main/module字段
  }
}

4. 导入/导出的语法不一致 #

这个错误经常出现在导出和导入的语法不匹配时：

• 如果Common包中用export default function MyFunc() {}，那么Web包中应该用import MyFunc from '@my-project/common'，而非import { MyFunc } from '@my-project/common'
• 如果用的是命名导出export function MyFunc() {}，则导入必须用import { MyFunc } from '@my-project/common'

最后检查步骤 #

1. 在根目录重新运行yarn install，确保所有软链接正确建立
2. 确认Common包已经编译完成，dist目录存在且包含编译后的JS和d.ts文件
3. 重启Web包的开发服务器，确保加载了最新的编译文件

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