majiayu000 Monorepo 项目规范
适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。
Purpose
规范 Monorepo 项目的目录结构、依赖管理、任务编排和包发布流程，确保多包协作的构建效率和版本一致性。
Procedure
- 先确认仓库是否已使用 pnpm workspace、Turborepo 或 Nx，并沿用现有包命名与任务约定。
- 将应用放在
apps/，共享库、配置和工具放在packages/或既有等价目录。 - 内部依赖使用
workspace:*，通过依赖图驱动构建顺序。 - 为 build、lint、test 配置可缓存、可并行、可增量的根任务，并明确输入、输出和环境变量。
- 在 Turborepo/Nx 中配置 affected/changed 范围命令，CI 优先跑受影响包，同时保留主干全量验证入口。
- 发布包前检查包边界、循环依赖、exports、peer dependencies 和版本策略。
工具选择
| 工具 | 适用 | 特点 |
|---|---|---|
| pnpm workspace | 基础 | 依赖提升、链接、脚本聚合 |
| Turborepo | 推荐 | 缓存、并行、依赖图 |
| Nx | 大型 | 增量构建、云缓存、插件生态 |
目录结构
pnpm + Turborepo
├── package.json # 根 package，workspace 配置
├── pnpm-workspace.yaml # workspace 包列表
├── turbo.json # Turborepo 配置
│
├── apps/
│ ├── web/ # 主应用
│ │ ├── package.json
│ │ └── ...
│ ├── admin/ # 管理后台
│ └── docs/ # 文档站
│
├── packages/
│ ├── ui/ # 共享 UI 组件
│ │ ├── package.json
│ │ └── src/
│ ├── utils/ # 工具函数
│ ├── config-eslint/ # 共享 ESLint 配置
│ └── config-typescript/ # 共享 TS 配置
│
└── tooling/ # 构建/测试工具（可选）
└── scripts/
pnpm-workspace.yaml
packages:
- "apps/*"
- "packages/*"
依赖管理
- 内部包使用
workspace:*协议 - 根
package.json统一部分依赖版本，子包可覆盖 - 禁止循环依赖，通过
pnpm why检查
{
"dependencies": {
"@repo/ui": "workspace:*",
"@repo/utils": "workspace:*"
}
}
Turborepo 任务编排
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**"]
},
"lint": {
"dependsOn": ["^build"]
},
"test": {
"dependsOn": ["^build"]
}
}
}
^build表示先执行依赖包的 buildoutputs用于缓存命中判断inputs应包含源码、配置、锁文件和环境相关文件；不要把.envsecret 值写入缓存 key- 远程缓存要区分可信 CI 与本地开发，避免把含敏感信息的产物上传
Nx 任务编排
{
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
"outputs": ["{projectRoot}/dist"],
"cache": true
}
}
}
包命名
- 内部包：
@org/package-name或@repo/package-name - 发布到 npm：遵循
@scope/name规范
Constraints
- 子包之间通过
workspace:*引用，不发布到 npm 再安装 - 共享配置（ESLint、TS）放在
packages/config-*，子包 extends - 构建顺序由依赖图决定，不手动指定无关依赖
- 根目录执行
pnpm -r build或turbo run build时，所有包按序构建 - 禁止循环依赖，新增包时通过
pnpm why检查依赖链 - CI cache 只缓存依赖安装目录和任务产物，不缓存未验证的构建状态
- affected 构建不能替代发布前全量验证；主干或 release 分支仍需完整质量门禁
Expected Output
- Monorepo 目录结构清晰（
apps/应用、packages/共享包、tooling/工具） pnpm-workspace.yaml和turbo.json/nx.json配置正确- 内部包使用
workspace:*协议，无循环依赖 - 构建、lint、test 任务可通过根命令一键执行，缓存命中率高
- CI 能区分 affected 快速反馈和 release 全量验证，缓存配置不会泄露密钥或隐藏依赖边界问题