Monorepo 与 pnpm workspace
多个前端项目共享组件、工具函数与配置时,Monorepo 能显著降低重复与版本漂移。
什么时候适合 Monorepo
- 多个应用共享一套组件库
- 工具函数、类型定义需要跨项目复用
- 需要统一构建、测试与发布流程
- 团队规模足以承担额外的工程复杂度
如果只是两个互不相关的小项目,独立仓库往往更简单。
pnpm workspace 基础
根目录 pnpm-workspace.yaml:
packages:
- 'apps/*'
- 'packages/*'
典型结构:
apps/
web/
admin/
packages/
ui/
utils/
config/
根目录 package.json:
{
"private": true,
"scripts": {
"dev": "pnpm --filter web dev",
"build": "pnpm -r build"
}
}
依赖管理
pnpm -r build:递归执行所有包的 buildpnpm --filter web add axios:只给指定应用安装依赖pnpm --filter ui add -D typescript:给指定包安装开发依赖workspace:*:引用本地包,避免误发到 registry
{
"dependencies": {
"@tanzhenxing/ui": "workspace:*"
}
}
共享配置
把 ESLint、TypeScript、Tailwind 配置抽到 packages/config:
// packages/config/tsconfig.base.json
{
"compilerOptions": {
"strict": true,
"moduleResolution": "bundler",
"skipLibCheck": true
}
}
各子包通过 extends 复用,减少重复配置。
构建与缓存
- 使用
pnpm -r按依赖顺序构建 - 大仓库可引入 Turborepo / Nx 做任务缓存
- 只构建受影响的包,缩短 CI 时间
- 产物与源码分离,避免把
dist提交到仓库
常见问题
- 幽灵依赖:pnpm 严格隔离后,未声明的依赖无法访问,需要显式声明
- 版本不一致:同一依赖在不同包中出现多个版本,用
pnpm why排查 - 循环依赖:包之间互相引用,需要重新划分边界
- 构建顺序:本地包必须先构建才能被应用引用
- 发布管理:多包发版需要 changesets 之类的工具
实践建议
- 包边界按职责划分,而不是按文件类型
- 共享代码优先抽成独立的
packages,不要用相对路径跨应用引用 - 统一 Node 版本与包管理器版本
- CI 缓存
pnpm store与构建产物 - 保持根目录脚本简单、可组合