1. 为什么你的团队需要一个 Monorepo 工程化体系?
我见过太多团队在项目初期,为了快速上线,把代码规范、格式检查这些“基建”工作往后放。结果呢?三个月后,代码库变成了一个没人敢动的“屎山”——TypeScript 配置五花八门,ESLint 规则形同虚设,Prettier 格式化全靠手动。每次 Code Review 都像在玩“大家来找茬”,团队成员互相抱怨代码风格不统一,合并分支时冲突多到让人崩溃。
如果你也遇到过这些问题,那今天这篇文章就是为你准备的。我要带你从零开始,搭建一个真正能用、好用、团队爱用的 Monorepo 工程化体系。这不是那种只讲理论的教程,而是我踩过无数坑、在十几个实际项目中验证过的实战方案。
简单来说,我们要实现的目标是:在一个仓库里管理多个项目(比如前端应用、后端服务、共享组件库),同时保证所有代码都遵循统一的 TypeScript 类型检查、ESLint 代码规范和 Prettier 代码格式化。更重要的是,这个流程要自动化——代码提交前自动检查,不符合规范的根本提交不上去。
听起来很复杂?别担心,我会用最直白的方式,一步步带你实现。我们先从最基础的环境搭建开始。
2. 环境准备与项目初始化
2.1 工具选型:为什么是 pnpm?
在开始之前,我们先聊聊工具选择。市面上包管理器不少,为什么我强烈推荐 pnpm 来做 Monorepo?
我最早用 npm,后来换 yarn,最后锁定 pnpm,根本原因就两个字:效率。pnpm 的硬链接机制,让同样的依赖在磁盘上只存一份。你可能没概念这能省多少空间,我举个例子:我们团队有个项目,用 npm 安装后 node_modules 占了 2.3GB,换成 pnpm 后只有 800MB。更重要的是安装速度——pnpm 的依赖提升(hoisting)策略,让安装时间从原来的 5 分钟缩短到 1 分钟。
安装 pnpm 很简单,如果你已经装了 Node.js(建议 16.17 或更高版本),一行命令搞定:
npm install -g pnpm
安装完成后验证一下版本,确保是 7.0.0 或更高:
pnpm -v
2.2 创建项目骨架
现在我们来创建项目的基本结构。打开终端,执行以下命令:
# 创建项目目录
mkdir my-monorepo && cd my-monorepo
# 初始化根目录的 package.json
pnpm init
初始化时,你可以一路回车用默认值,或者按需修改。我建议把 name 改成带 scope 的形式,比如 @your-org/monorepo,这样更规范。
接下来是关键一步:创建 pnpm-workspace.yaml 文件。这个文件定义了哪些目录属于工作区(workspace),也就是哪些是我们要管理的子包。
# pnpm-workspace.yaml
packages:
- 'packages/*' # 所有共享包都放在这里
- 'apps/*' # 所有应用都放在这里
- 'tools/*' # 工具脚本可以放这里
这个配置告诉 pnpm:“嘿,packages、apps、tools 这三个目录下的每个子文件夹,都是一个独立的包,你要把它们当成一个整体来管理。”
现在创建目录结构:
# 创建核心目录
mkdir -p packages/core
mkdir -p packages/ui
mkdir -p apps/web-app
mkdir -p apps/admin-app
mkdir -p tools/scripts
你的项目结构现在应该是这样的:
my-monorepo/
├── package.json
├── pnpm-workspace.yaml
├── packages/
│ ├── core/ # 核心工具库
│ └── ui/ # UI 组件库
├── apps/
│ ├── web-app/ # 用户端应用
│ └── admin-app/ # 管理后台应用
└── tools/
└── scripts/ # 构建脚本等工具
2.3 创建第一个子包
让我们先创建最基础的 core 包。进入 packages/core 目录:
cd packages/core
pnpm init
修改生成的 package.json,我建议你这样配置:
{
"name": "@your-org/core",
"version": "1.0.0",
"description": "共享工具函数库",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"files": ["dist"],
"scripts": {
"build": "tsc",
"dev": "tsc --watch"
},
"keywords": [],
"author": "",
"license": "MIT"
}
注意 name 字段,我用了 @your-org/core 这种带 scope 的命名。这样做有两个好处:一是避免和 npm 上的公共包重名,二是在代码中引用时一目了然,知道这是内部包。
用同样的方法,创建 ui 包和两个应用包。每个包的 package.json 都要根据实际用途调整。比如 apps/web-app 可能用 Vite 或 Next.js,那 scripts 里就要有 dev、build 等命令。
2.4 安装共享依赖
这是 pnpm workspace 的第一个魔法时刻。我们要在根目录安装 TypeScript,这样所有子包都能共享这个依赖。
回到项目根目录:
cd ../.. # 回到 my-monorepo 根目录
pnpm add typescript -D -w
注意 -w 参数,它代表 --workspace-root,意思是“把这个依赖安装在根目录”。如果不加 -w,pnpm 会报错提醒你——这是 pnpm 的贴心设计,防止你误操作。
安装完成后,你会在根目录的 package.json 里看到 TypeScript 出现在 devDependencies 中。但更重要的是,所有子包现在都能直接使用 TypeScript 了,不需要在每个子包里单独安装。
3. 配置统一的 TypeScript 环境
3.1 创建基础 TypeScript 配置
TypeScript 配置是 Monorepo 里最容易混乱的部分。每个团队可能都有自己的习惯,但经过多个项目实践,我总结出了一套“黄金配置”。
在根目录创建 tsconfig.base.json:
{
"compilerOptions": {
// 目标 ECMAScript 版本
"target": "ES2020",
// 模块系统
"module": "ESNext",
"moduleResolution": "Node",
// 严格类型检查
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"strictBindCallApply": true,
"strictPropertyInitialization": true,
"noImplicitThis": true,
"useUnknownInCatchVariables": true,
"alwaysStrict": true,
// 模块解析
"baseUrl": ".",
"paths": {
"@your-org/*": ["packages/*/src"],
"@apps/*": ["apps/*/src"]
},
// 互操作性
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"resolveJsonModule": tru
174



被折叠的 条评论
为什么被折叠?



