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:递归执行所有包的 build
  • pnpm --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 提交到仓库

常见问题

  1. 幽灵依赖:pnpm 严格隔离后,未声明的依赖无法访问,需要显式声明
  2. 版本不一致:同一依赖在不同包中出现多个版本,用 pnpm why 排查
  3. 循环依赖:包之间互相引用,需要重新划分边界
  4. 构建顺序:本地包必须先构建才能被应用引用
  5. 发布管理:多包发版需要 changesets 之类的工具

实践建议

  • 包边界按职责划分,而不是按文件类型
  • 共享代码优先抽成独立的 packages,不要用相对路径跨应用引用
  • 统一 Node 版本与包管理器版本
  • CI 缓存 pnpm store 与构建产物
  • 保持根目录脚本简单、可组合