Monorepo 是通过统一依赖管理、共享配置、原子化提交和跨模块复用解决多包协作问题的工程体系；核心是模块源码直连、配置一处生效、增量构建与智能发布；主流工具为 Turborepo（高性能构建）、Nx（全功能平台）、pnpm workspaces（轻量灵活），可组合使用。
Monorepo（单体仓库）在 JavaScript 项目中已成为管理多个相关模块的主流方案，尤其适合工具库、组件库、微前端或全栈应用等场景。它不是简单地把多个项目塞进一个 Git 仓库，而是通过统一的依赖管理、共享配置、原子化提交和跨模块复用，解决多包协作中的版本混乱、重复构建、本地调试困难等问题。
核心目标：统一管理 + 高效复用
Monorepo 的本质是“一套工程体系管多个逻辑模块”。关键不在于目录结构多漂亮，而在于能否让以下事情变得自然：
- 模块 A 修改后，模块 B 能立刻以源码形式消费，无需发布再安装
- 所有模块共用同一套 ESLint、TypeScript、Jest 配置，且一处更新全局生效
- CI 构建时只编译/测试实际变更的模块及其下游依赖（增量构建）
- 发布时能自动识别哪些包有变更、按语义化版本号生成发布清单
主流工具选型与定位
目前 JavaScript 生态中，三种方案覆盖绝大多数需求：
- Turborepo：聚焦构建性能与任务调度，原生支持缓存、远程缓存、任务图谱和智能增量执行；适合中大型团队对 CI/CD 效率敏感的场景；不处理包发布，需搭配其他工具
- Nx：功能最全的“平台级”工具，内置代码生成、影响分析、分布式任务执行、插件生态（React/Vue/Angular 全支持）；学习成本略高，但长期维护性好
- pnpm workspaces：轻量灵活，基于符号链接实现本地依赖解析，零配置即可启用；适合中小项目或想从传统多 repo 平滑过渡的团队；需自行组合构建/测试/发布流程
三者并非互斥——例如可用 pnpm 管理 workspace，用 Turborepo 调度构建任务，用 Changesets 管理版本与发布。
立即学习“Java免费学习笔记（深入）”；
依赖管理的关键实践
Monorepo 中的依赖分三类，处理方式各不相同：
-
内部依赖（workspace 包）：必须使用
workspace:^或workspace:*协议（如"my-utils": "workspace:^1.0.0"），确保 pnpm/yarn/npm 正确链接到本地源码；禁止手动写相对路径或固定版本号 -
外部依赖（三方库）：建议提升到根
package.json的devDependencies或dependencies，子包通过peerDependencies声明兼容范围；避免各包重复安装不同小版本 -
类型依赖（@types/*）：统一放在根目录，子包不再单独安装；配合 TypeScript 的
references或paths映射，保证类型即刻生效
模块间通信与边界控制
模块解耦不是靠物理隔离，而是靠约定与工具约束：
- 用
project.json（Nx）或turbo.json显式声明模块依赖关系，禁止跨层调用（如 UI 组件包直接引用数据库 client） - 通过
eslint-plugin-import或@nx/eslint-plugin启用no-restricted-imports规则，拦截非法导入路径 - 公共类型/常量应收敛到独立的
types或shared包，而非在业务模块中散落定义
不复杂但容易忽略
