TypeScript monorepo 怎么配置

在日常开发中，我们常会遇到这样的场景：做一个电商项目时，需要把用户管理、商品展示、订单处理这些功能拆成独立的模块，方便团队分工、后期复用。可如果每个模块都是单独的仓库，不仅要重复配置构建、测试工具，跨模块调用时还得频繁发版本，效率特别低。这时候，TypeScript Monorepo 就是解决这类问题的好办法。

什么是 Monorepo？简单说，它就是把多个相关项目放在同一个代码仓库里管理。而结合 TypeScript 的特性，还能解决跨模块类型不兼容、引用混乱的问题。

第一步：初始化仓库与基础配置

先新建一个空文件夹作为仓库根目录，打开终端执行 npm init -y 生成 package.json，再新建 tsconfig.json 作为整个 Monorepo 的基础 TypeScript 配置。这里不用写太复杂的规则，只要包含通用配置就行，比如 "compilerOptions": { "target": "ES2020", "module": "commonjs", "strict": true }，后续子项目可以基于这个配置扩展。

然后，新建一个 packages 文件夹，用来放所有子模块——就像把不同功能的盒子放在同一个收纳柜里，方便统一管理。

第二步：配置子模块的本地引用

假设我们做两个子模块：user-utils（处理用户相关逻辑）和 order-utils（处理订单相关逻辑）。在 packages/user-utils 里新建 index.ts，写个简单的函数：export const getUserName = (id: number) => 用户${id};。

如果想在 order-utils 里直接调用这个函数，不用把 user-utils 发布到 npm，只要在 order-utils 的 package.json 里加一行："dependencies": { "user-utils": "workspace:*" }。这里的 workspace:* 是 npm 专门给 Monorepo 用的标识符，意思是“找本地 packages 里的 user-utils 模块”。

第三步：解决类型自动识别问题

刚这么配置完，你可能会发现：order-utils 里导入 getUserName 时，TypeScript 会报错说“找不到模块”。这是因为我们没给 user-utils 声明类型文件。

在 user-utils 的 package.json 里加两个配置："main": "dist/index.js"（指定编译后入口文件）和 "types": "dist/index.d.ts"（指定类型声明文件）。然后在 user-utils 根目录新建 tsconfig.json，基于根目录的配置，加 "outDir": "./dist"（把编译后的文件放在 dist 文件夹），再执行 npx tsc 编译，就能自动生成类型文件了。

第四步：统一管理依赖与脚本

如果每个子模块都单独装依赖，不仅占空间，还容易出现版本不一致的问题。根目录的 package.json 里加 "workspaces": ["packages/*"]，这样 npm install 时，会自动把所有子模块的依赖都装在根目录的 node_modules 里，子模块可以直接用。

还能在根目录的 package.json 里写统一脚本，比如 "scripts": { "build": "npm run build --workspaces" }，执行这个命令，就能一键编译所有子模块，不用一个个手动跑。

小提醒：常见坑避坑

如果跨模块调用时还是提示类型错误，先检查两个点：一是子模块的 types 路径是否正确，二是有没有执行编译生成类型文件。另外，Monorepo 不是越大越好，别把不相关的项目硬塞进来，不然会增加构建和管理的复杂度——就像收纳柜里只放常用的盒子，闲置的单独放，才方便找东西。