做后端开发这些年我见过太多团队在同一个泥坑里反复挣扎微服务拆了一地仓库建了几十个每次跨服务改需求都要提好几个 PR等 Review 等到下班换个分支切来切去合并冲突能磨掉半天。于是很多人抱着“让代码回到一个仓库”的念头转向 monorepo结果又遇上另一批问题构建慢、依赖乱、工具链复杂、团队约定靠嘴传。最近在 Hacker News 上看到一个项目叫 NoDiff定位是“a framework that lives in your monorepo”。这个名字本身就很有意思一个不希望你在合并时看到一堆 diff 的框架。它的想法不是把仓库拆得更碎也不是发明一套新语言而是直接在 monorepo 里提供一套框架级的协作和开发机制让团队之间减少版本偏差、减少重复劳动、减少那些本不该出现的 merge conflict。这篇文章不打算只复述项目简介。我更想和你一起拆解 monorepo 工程化里真正让人头疼的部分分析 NoDiff 这类“monorepo 内嵌框架”到底想解决哪些实际问题然后给出一套可落地的 monorepo 框架选型、目录设计、构建优化和 CI 配置方案。就算你暂时用不上 NoDiff这套思路也值得收藏备用。1. 这篇文章真正要解决的问题先说实话Monorepo 不是银弹。我见过不少团队把多个项目塞进一个仓库后第一周很开心一个月后开始焦虑。问题集中在几个地方第一是工具链割裂。不同语言、不同构建工具、不同依赖管理方式混在一个仓库里光让前端、后端、脚本三套工具联合起来就够折腾。根目录的package.json、pom.xml、go.mod并存的情况并不少见。第二是构建效率。仓库变大后任何一个子项目的改动都可能触发整仓构建。没有增量缓存、没有任务编排的话CI 排队时间会越来越长。第三是协作摩擦。多个团队改同一个仓库互相覆盖文件、依赖升级影响未知、分支合并时出现大量无关 diff。代码审查明明应该关注逻辑结果一半时间在处理冲突和琐碎噪声。NoDiff 选择“住在 monorepo 里”本质上是在尝试一个方向把 monorepo 从“一堆代码的集合”变成“一个可编程的工程系统”。框架不再是外部强加的工具而是和仓库结构、依赖图、构建流程长在一起。如果你正在做以下事情这篇文章会特别适合你打算从多仓库迁到 monorepo但不知道目录怎么拆、构建怎么做增量已经在用 monorepo但感觉依赖管理和 CI 越来越难维护对框架设计感兴趣想知道一个“长在 monorepo 里的框架”和传统构建工具的区别。2. Monorepo 是什么它真正改变的是协作模型2.1 Monorepo 的概念边界Monorepo全称 Monolithic Repository指在一个版本控制仓库中管理多个项目或包的代码组织方式。注意它和单体应用Monolith是两个概念monorepo 是代码存储和工程组织层面的选择你的业务部署方式可以是微服务也可以是单体服务。一个典型的 monorepo 结构长这样my-monorepo/ ├── apps/ │ ├── web/ # 前端应用 │ ├── admin/ # 后台管理应用 │ └── api/ # 后端 API 服务 ├── packages/ │ ├── ui/ # 共享 UI 组件 │ ├── utils/ # 公共工具函数 │ ├── config/ # 统一配置 │ └── types/ # 共享类型定义 ├── tools/ │ ├── scripts/ # 构建脚本 │ └── generators/ # 代码生成器 ├── package.json ├── pnpm-workspace.yaml └── tsconfig.base.json这里的关键不是“所有代码放一起”而是用一套工具链来管理它们之间的依赖关系和构建顺序。2.2 Monorepo 解决了什么又带来了什么对比多仓库Multi-repomonorepo 最明显的收益是三点依赖统一。多个项目可以共享同一个依赖版本升级公共库时只改一处。多仓库里常见的问题是“项目 A 升级了 SDK项目 B 还在用旧版本”跨仓库改代码要开多个 PR 并且按顺序合并非常痛苦。原子提交。一次提交可以同时包含前端、后端和共享包的改动。这对于跨端需求特别友好Review 时能在一个 PR 里看到完整上下文。重构范围可控。在 monorepo 中做跨项目重命名、接口调整IDE 能基于真实代码路径感知影响范围。多仓库模式下重构经常要靠人肉搜索。但 monorepo 也带来了新的成本仓库体积增长git clone时间变长依赖图变得复杂一个包升级可能导致很多下游包受影响如果没有增量构建CI 时间会线性增长权限管理不如多仓库灵活。这就是 NoDiff 这类框架存在的基础它假设你选择了 monorepo然后帮你解决“选定之后”的工程问题。2.3 “框架住在仓库里”到底意味着什么传统工具的交互模式是“外部工具 配置文件”。比如你装一个构建工具它在运行时读取仓库中的配置文件执行完就退出。仓库对工具来说只是输入。而 NoDiff 的定位不同。“NoDiff, a framework that lives in your monorepo”这句话我的理解是它把框架代码和工程约定直接写进仓库结构里。也就是说你的 monorepo 不仅是代码仓库同时也包含一套可执行的工程框架。这类设计通常体现为几个能力把构建、测试、发布流程封装成仓库内可见的脚本或 API通过依赖图自动推导构建顺序而不是靠人工记忆在框架层面统一配置、代码风格、环境变量管理将来可能进一步做到让框架基于仓库状态自动生成 CI 步骤、自动触发受影响模块的测试。这种思路其实是把“工程规范”沉淀为“代码”而不是留在团队文档里。规范一旦变成代码就有了版本、可以测试、可以被 CI 强制校验。这比贴一份《团队开发规范.md》要可靠得多。3. NoDiff 想消灭的是协作中的“无效差异”3.1 为什么 Diff 会成为问题“Diff”本身是软件开发的基础操作。Git 的 diff 让我们能看清改动、做 Code Review、回滚变更。但实际项目中很多 diff 并不是有效的信息传递而是噪音。例如某个包升级后大量package-lock.json行被改动不同开发者的 IDE 自动格式化导致无关代码行变化多人同时在根目录配置文件中追加内容产生冲突分支长时间未同步合并时要处理一堆“假冲突”。这些噪音浪费了 Review 的时间也掩盖了真正重要的逻辑变更。3.2 从“对比结果”走向“约束过程”NoDiff 这个名字按我的理解它不是要取消 Git 的 diff 能力而是试图在框架层面通过结构和流程约束从根源上减少无用 diff 的产生。这会带来几个可见的变化方向改动范围可视化。框架知道你的包依赖图一个改动发生后能明确告诉你“这个改动影响了哪些包”而不是让你自己去猜。自动生成变更集。在 monorepo 里一次跨包改动往往需要同步修改多个文件。框架可以依据依赖关系自动识别需要同步的位置减少遗漏和手工核对。依赖升级影响评估。升级一个公共包时框架可以根据实际依赖图算出哪些项目会受影响并在提交前给出预警而不是合并完才在 CI 里发现。统一格式和约定。通过脚手架和生成器让新模块天然遵循仓库规范减少“同一个功能三种写法”的差异。这些能力本质上都是“利用仓库内的结构化信息替代人工经验判断”。3.3 它和新一代 monorepo 工具的关系看到这里你可能会有疑问NoDiff 是不是又一个 Lerna、Turborepo、Nx我的判断是它更像是在这些工具之上或侧面做的是“框架层”的事情。Lerna解决的是多包版本发布和依赖链接问题Turborepo核心是任务缓存和增量构建Nx提供了一套更完整的 monorepo 插件化能力NoDiff的关键词是“framework”和“lives in your monorepo”它更关注开发协作模型可能包含但不限于构建调度。从工程实践角度看它们不冲突。你仍然可以用 Nx 做构建缓存同时通过 NoDiff 这类框架生成变更集、约束提交规范、统一模块接入方式。这里想提醒一点现在 monorepo 工具生态正处在活跃期工具之间功能有重叠选型时不要追求“全家桶”而是抓住你团队最痛的那一两个问题能解决就值得引入。4. 搭建一个现代 Monorepo 的最小骨架不管用不用 NoDiff一个稳定的 monorepo 工程骨架是必须的。下面以目前前端社区比较成熟的 pnpm workspace 方案为例搭建一个包含前端应用、Node 服务和共享包的最小 monorepo。4.1 环境准备与前置条件在开始之前确认你的开发环境满足以下条件。版本以实际稳定版为准本文不做死板指定。操作系统macOS / Linux / Windows(WSL 更推荐) Node.js建议使用 18 及以上 LTS 版本 包管理器pnpm 8 及以上 版本控制Git 2.30 及以上安装 pnpmnpm install -g pnpm pnpm --version4.2 初始化仓库和 workspace创建项目根目录并初始化package.jsonmkdir my-monorepo cd my-monorepo npm init -y然后在根目录创建pnpm-workspace.yaml声明 workspace 包含的目录# 文件路径pnpm-workspace.yaml packages: - apps/* - packages/* - tools/*这个文件是 pnpm workspace 的核心。它告诉 pnpmapps下的每个子目录、packages下的每个子目录都是独立的包。接着安装开发依赖pnpm add -D typescript ts-node types/node --workspace-root4.3 设计包目录与依赖关系我们创建三个包演示典型的 monorepo 依赖结构packages/utils共享工具函数。packages/config共享 TypeScript 编译配置。apps/web一个使用 utils 的 Node 脚本应用。先创建 utils 包mkdir -p packages/utils/src为它创建package.json{ name: my-monorepo/utils, version: 1.0.0, main: ./src/index.ts, types: ./src/index.ts, scripts: { build: tsc }, dependencies: { typescript: workspace:* } }这里用workspace:*语法表示依赖仓库内的 TypeScript 版本而不是下载一个独立的实例。这是 pnpm workspace 避免依赖版本不一致的关键手段。在packages/utils/src/index.ts中写一个简单工具函数// 文件路径packages/utils/src/index.ts export function formatMoney(amount: number, currency CNY): string { return new Intl.NumberFormat(zh-CN, { style: currency, currency, }).format(amount); } export function sleep(ms: number): Promisevoid { return new Promise((resolve) { setTimeout(resolve, ms); }); }4.4 创建应用包并引用共享包创建 web 应用目录mkdir -p apps/web/src在apps/web/package.json中引用本地包{ name: my-monorepo/web, version: 1.0.0, main: ./src/index.ts, scripts: { start: ts-node src/index.ts }, dependencies: { my-monorepo/utils: workspace:* } }编写应用入口代码// 文件路径apps/web/src/index.ts import { formatMoney, sleep } from my-monorepo/utils; async function main() { console.log(订单金额, formatMoney(1999.5)); console.log(正在模拟耗时操作...); await sleep(500); console.log(完成。); } main();4.5 安装依赖并验证本地链接在仓库根目录执行pnpm install安装完成后pnpm 会把my-monorepo/utils以 workspace 协议链接到apps/web的node_modules中。你可以通过以下命令验证链接是否生效pnpm ls --depth -1运行应用pnpm --filter my-monorepo/web start预期输出类似订单金额¥1,999.50 正在模拟耗时操作... 完成。这一步跑通说明你的 monorepo 本地依赖已经可以工作了。后续无论有多少个应用和共享包都遵循同样的模式。5. 无 Diff 协作的关键提交规范与变更集管理如果只看目录结构和依赖链接monorepo 只算完成了一半。真正容易产生 diff 噪音的地方是多人协作时的提交、版本和变更记录。NoDiff 试图在框架层面解决的也正是这一块。5.1 用 Commitlint 约束提交信息一个固定的提交信息格式能显著减少 Review 时理解上下文的成本。常见的约定是 Conventional Commitsfeat: 新增订单导出功能 fix: 修复金额格式化精度问题 chore: 升级 eslint 依赖 docs: 更新 README refactor: 重构用户认证逻辑 test: 增加登录接口单元测试在 monorepo 中最好在提交信息里带上影响范围feat(web): 新增订单导出功能 fix(utils): 修复金额格式化精度问题使用 commitlint 可以强制校验。安装pnpm add -D commitlint/cli commitlint/config-conventional --workspace-root创建配置文件// 文件路径commitlint.config.js module.exports { extends: [commitlint/config-conventional], rules: { header-max-length: [2, always, 100], scope-enum: [ 2, always, [web, admin, api, utils, config, cli], ], }, };这样提交信息的 scope 只能出现在枚举列表里命名不规范直接报错。5.2 用 Changesets 管理多包版本发布在 monorepo 里发布多包版本最大的痛点是“改一个功能要手动记得到底哪些包需要发版”。Changesets 是解决这个问题的通用方案。安装pnpm add -D changesets/cli --workspace-root初始化pnpm changeset init规范流程是开发完一个功能后执行pnpm changeset选择受影响包、填写变更类型和描述Changesets 会生成一个 markdown 变更文件比如.changeset/eleven-dogs-smile.md发布时执行pnpm changeset version它会根据变更文件自动提升所有关联包的版本号并更新 CHANGELOG。这套机制保证了每次版本变更都有明确记录而且改动的包列表由依赖图推导不靠人工记忆。这正是“减少无效 diff”在版本管理维度的体现。5.3 用 TurboRepo 做增量任务调度monorepo 的 CI 不能每次全量构建。TurboRepo 是目前社区接受度较高的增量构建方案。安装pnpm add -D turbo --workspace-root配置turbo.json{ pipeline: { build: { dependsOn: [^build], outputs: [dist/**] }, test: { dependsOn: [build] }, lint: {} } }在根目录package.json中添加脚本{ scripts: { build: turbo run build, test: turbo run test, lint: turbo run lint } }TurboRepo 的核心能力是它会读取每个包的任务依赖关系自动确定执行顺序同时基于文件内容生成缓存如果某个包的输入没有变化任务结果直接复用缓存CI 时间能大幅缩短。6. 设计一套“减少 Diff”的模块接入约定6.1 统一目录规范NoDiff 这类框架的价值在于把“约定”变成“可执行”。当你新建一个模块时脚手架应该自动生成符合规范的目录和文件而不是让每个开发者手动创建再格式化一遍。以我们上面的骨架为例一个共享包的标准目录可以约定为packages/package-name/ ├── src/ │ ├── index.ts # 公共入口只导出对外 API │ ├── types.ts # 类型定义 │ └── __tests__/ # 单元测试 ├── package.json ├── tsconfig.json └── README.md约定一src/index.ts是唯一对外出口禁止从包内部路径直接引用。约定二公共入口文件不做重导出以外的任何逻辑。约定三每个包必须包含 README说明用途和维护者。这些约定一旦写在框架里就能通过代码检查自动验证而不是等人来 review。6.2 自动校验依赖范围引用本地包时最常见的错误是路径写错或者绕过 package.json 的 dependencies 直接跨包引用。可以在 ESLint 中配置规则来限制导入路径。安装相关依赖pnpm add -D eslint eslint-plugin-import --workspace-root在 ESLint 配置中添加规则// 文件路径.eslintrc.js module.exports { parser: typescript-eslint/parser, plugins: [import], rules: { import/no-extraneous-dependencies: [ error, { packageDir: [./] } ] } };这样如果你在apps/web里引用了packages/config但没有在 dependencies 中声明CI 会直接报错。6.3 分支策略与合并规范减少 diff 的另一半靠的是 Git 使用习惯。在 monorepo 中推荐以下做法每个功能从最新的main分支切出分支生命周期尽量短提交信息遵循 Conventional Commits使用git pull --rebase保持提交历史线性定期同步主干避免分支长期落后尽量使用 squash merge 合并 PR保持主干历史干净。如果你希望团队成员强制遵守这些规则可以在 CI 中加入分支命名检查。例如用脚本校验分支名是否符合feat/xxx、fix/xxx、chore/xxx的格式。7. CI 中的 Monorepo 增量策略与缓存设计monorepo 工程的 CI 设计核心目标是“只做必要的构建和测试”。7.1 根据变更路径触发任务在 GitHub Actions 中可以通过paths配置让不同目录的改动触发不同的 job# 文件路径.github/workflows/ci.yml name: CI on: pull_request: branches: [main] paths: - apps/web/** - packages/** - pnpm-lock.yaml jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: pnpm/action-setupv2 with: version: 8 - uses: actions/setup-nodev4 with: node-version: 18 cache: pnpm - name: Install dependencies run: pnpm install --frozen-lockfile - name: Build affected packages run: pnpm --filter my-monorepo/web build如果想让变更路径自动影响多个包可以结合 Turborepo 的--filter...[origin/main]语法pnpm turbo run build --filter...[origin/main]这行命令的含义是找出和origin/main相比有改动的包以及依赖这些包的包然后只构建它们。这是目前 monorepo CI 里最实用的增量策略之一。7.2 缓存与锁文件注意事项使用 pnpm 时CI 中必须使用--frozen-lockfile保证锁文件不被 CI 环境悄悄改动。缓存 node_modules 时缓存键应包含pnpm-lock.yaml的哈希。构建产物缓存应区分不同包避免一个包产物变化导致全局缓存失效。7.3 如何判断 CI 是否健康一个好的 monorepo CI 有几条判断标准大多数 PR 的构建时间在 10 分钟以内未改动包的任务不会重复执行缓存命中率稳定不因文件 mtime 变化而失效提交信息不合规时CI 能在 1 分钟内给出明确提示。如果你们团队的 CI 不满足这些标准先不要急着上更多工具优先把增量策略和缓存设计做好。NoDiff 这类框架如果融入了 CI 调度也会依赖这套基础能力。8. 常见问题与排查思路问题现象可能原因排查方式解决方案pnpm install后本地包找不到workspace 目录配置遗漏检查 pnpm-workspace.yaml 路径是否正确执行pnpm ls修正 packages 配置重新 install包 A 引用包 B 但 CI 报模块缺失未在 package.json 声明依赖检查 A 的 dependencies 是否包含 B添加xxx/b: workspace:*TurboRepo 缓存未命中输入文件变化或缓存键设计不合理查看 turbo trace 日志调整 pipeline 的 inputs 和 outputs提交被 commitlint 拦截提交信息不符合规范查看报错提示按 Conventional Commits 重写提交信息多个包升级同一依赖后版本不一致workspace 协议使用不规范pnpm list检查依赖版本统一使用 workspace 协议或在根目录声明依赖CI 全量构建时间过长未使用增量构建检查 CI 脚本是否全量执行引入 TurboRepo 或按变更路径裁剪任务git merge 出现大量 lock 文件冲突分支长期落后且依赖经常变动查看git log和冲突文件定期 rebase升级依赖尽量放在 PR 开头这里特别提醒一下 lock 文件冲突。在 monorepo 中pnpm-lock.yaml是所有依赖关系的全局事实表改动频率高分支合并时经常冲突。缓解办法是依赖升级单独开 PR、快速合并或使用pnpm install重新生成锁文件但要注意完整 review 变更内容避免意外引入不兼容版本。9. 生产环境中的 Monorepo 最佳实践9.1 从单仓库迁移过来时的渐进策略不需要把所有项目一次性塞进 monorepo。更稳妥的路径是先搭建 monorepo 骨架接入新项目把与业务无关的公共包工具函数、类型定义、UI 基础组件迁移进去验证构建、发布、CI 全流程稳定后再迁移业务项目迁移过程保留旧仓库只读状态确认稳定后再归档。9.2 权限与代码保护monorepo 不等于团队都能改任何包。在 CI 中加入 CODEOWNERS 机制可以按目录指定负责人# 文件路径CODEOWNERS apps/payment/** payment-team apps/order/** order-team packages/utils/** platform-team这样代码审查系统会在改动对应目录时自动指定 reviewer。9.3 环境变量与密钥管理统一管理环境变量也是框架可以承担的职责。推荐做法非敏感配置写入.env.example并纳入版本控制敏感配置通过 CI 平台的 secret 注入禁止提交进仓库尽量约定单一配置入口避免每个包各自读取.env。如果框架本身支持配置中心集成应该把配置加载逻辑统一封装而不是让每个应用重复实现。9.4 依赖治理Monorepo 依赖治理的核心是“根依赖优先”。能放在根目录的共用依赖不要在不同包内重复安装。可以用 pnpm 的-w参数pnpm add -D typescript -w每个包的package.json保持精简只有真正属于该包的依赖才声明。这样依赖图会清晰很多。9.5 关注框架自身的收纳能力回到 NoDiff 这个项目。对于这种“生活在 monorepo 中的框架”实践层面的建议是不要把它当作全自动的魔法而是当作团队工程规范的代码化载体。框架能帮你做的是生成标准目录、校验依赖边界、计算受影响范围、管理变更集、调度增量构建但它不能帮你定义“什么是好的模块划分”不能替团队思考兼容性策略。真正合理的路径是先把团队的 monorepo 骨架和协作流程搭建起来明确哪些规则需要强制、哪些需要引导然后再选择或定制一个适合的框架来承载这些规则。NoDiff 如果还在早期阶段接入前要重点看它的维护活跃度、插件机制、与现有工具链的兼容性以及迁移成本。另外提醒一句任何框架在引入生产环境之前都要在测试仓库里跑通完整的“创建模块 → 开发 → 构建 → 测试 → 版本发布 → 部署验证”链路并确认有快速回滚方案。框架层引入的风险比普通依赖大因为它会影响所有子项目的开发方式。