在 monorepo 里做代码评审时最让人头疼的往往不是核心逻辑写错了而是 diff 里塞满了无关内容。依赖锁定文件被格式化、两个子包的 tsconfig 参数不一致、生成文件被本地环境重写了一遍这些噪声会把真正该看的代码变更淹没。NoDiff 这个名称听起来像“没有差异”但它并不是消灭 diff而是把 monorepo 里那些不应该出现的、机械性的差异收掉让每次提交回到“只有有意义的变更”这个状态。与其说 NoDiff 是一个独立的 CLI 工具不如说它是“住在你的 monorepo 里”的一层框架它和仓库一起提交、一起演进负责统一配置生成、依赖一致性和变更影响分析。这套思路特别适合正在经历仓库从单包向多包演进的团队。多仓时代每个仓库自己维护一套配置问题被隔离在各个工程里一旦切换到 monorepo所有子包的 tsconfig、eslint 规则、构建脚本、依赖版本都集中在一起任何一处漂移都会立即暴露在 diff 和构建日志中。本文会从 monorepo 中 diff 噪音的成因讲起再给出一个 NoDiff 风格的最小实现最后落到 CI 集成、常见排错和团队落地建议。1. 为什么 monorepo 里的 diff 会失控1.1 monorepo 的收益与代价monorepo 的核心收益是统一统一依赖版本统一构建流程统一代码规范跨包改动可以在同一个提交里原子完成。比如某个底层库改了导出签名调用方函数库和 Web 应用可以在同一次提交中一起调整review 者能直观看到“接口变了调用方也同步变了”。代价也很明显。原来多个独立仓库各自维护一套配置配置漂移不容易被察觉现在所有子包的配置、锁文件、生成文件都在同一个仓库里任何一台开发机、任何一个 Node 版本、任何一次依赖安装操作都可能产生大量无关 diff。这些 diff 会降低 review 效率也会让基于 diff 的自动化流程更难聚焦。1.2 diff 噪音的常见来源从实际经验看monorepo 里的 diff 噪音主要来自四类锁文件变化。pnpm-lock.yaml、yarn.lock、package-lock.json 对安装顺序和解析结果很敏感不同包管理器、不同 Node 版本、不同操作系统环境都可能重写它们。子包配置文件漂移。多个子包各自维护 tsconfig.json、eslint.config.js、prettier.config.js一旦某次调整没有同步到所有子包就会出现参数不一致。生成文件被误提交。dist 目录、构建缓存、Protobuf 生成的代码、Rust 的 Cargo.lock 等文件如果被本地环境重新生成就会产生无意义的 diff。scripts 命名不统一。有些子包用 build有些用 compile有些用 make:buildreview 时看不出这次变更是否真的改变了构建行为。这些噪音叠加在一起会让代码评审从“看逻辑”退化成“找逻辑”。NoDiff 想解决的就是不要让配置、生成文件和依赖差异出现在日常提交里。1.3 NoDiff 的思路让 diff 只承载业务含义NoDiff 不追求“所有文件都不变”而是追求“该变的变不该变的绝不误报”。它把 monorepo 中应由框架统一管理的部分收拢到仓库根目录以根配置为基准按需生成每个子包的配置文件并在 CI 中强制校验。开发者日常能看到的 diff要么是业务代码要么是根配置主动调整后同步出来的结果。这样也能避免一个常见陷阱每个子包都允许自由修改自己的配置表面上灵活实际上会导致子包之间的配置逐渐分化。NoDiff 的思路是“根配置统一生成子包只保留必要的覆盖”把配置差异从默认状态变成显式声明。注意NoDiff 不是要禁止子包自定义配置而是要求自定义的部分显式写在配置文件中并且由检查命令确认。隐式漂移是 diff 噪音的根源显式覆盖则属于正常工程决策。2. NoDiff 的技术定位一个“住在仓库里”的框架2.1 它不是又一个全局 CLI而是仓库的一部分“lives in your monorepo”这句话是理解 NoDiff 的关键。传统的脚手架工具会在仓库之外维护一套模板项目初始化后再也不管NoDiff 的思路恰恰相反它作为仓库内的一个框架层存在clone 下来就有配置变更会跟随版本库一起提交。这意味着三个实际结果新成员接入成本低。clone 仓库后不需要额外安装全局依赖仓库根目录的 scripts 和配置文件已经把行为标准固定下来。配置变更可审查。调整 Node 版本、tsconfig 基座、依赖策略时改动会出现在代码评审中而不是躲在某台机器的全局目录里。版本与仓库强绑定。NoDiff 的扫描逻辑、配置解析逻辑和仓库本身一起演进仓库重构时框架同步改不会出现“工具已经升级仓库还在跑旧逻辑”的情况。2.2 核心能力拆解NoDiff 在 monorepo 里主要承担三件事第一配置生成。根据根配置生成每个子包的 tsconfig、eslint、prettier 等基础配置。子包不需要手写重复文件只需要声明它与默认配置的差异。第二一致性校验。检查每个子包的 package.json 依赖版本是否符合根配置的 dependencyPolicy检查配置生成结果与仓库当前文件是否一致。CI 中校验不通过就终止构建。第三变更影响分析。利用 git diff 的文件路径匹配子包目录计算出此次变更影响哪些包进而决定哪些包需要跑测试、哪些包需要构建。这是 monorepo 中做增量 CI 的基础能力。2.3 目录结构与最小配置以常见的 pnpm TypeScript monorepo 为例NoDiff 风格的仓库结构大致如下monorepo-sample/ ├── package.json ├── pnpm-workspace.yaml ├── nodiff.config.ts ├── scripts/ │ ├── scan.ts │ ├── check.ts │ └── affected.ts ├── packages/ │ ├── app-a/ │ │ ├── package.json │ │ └── src/ │ └── lib-b/ │ ├── package.json │ └── src/根目录的 nodiff.config.ts 是整套行为的基准import { defineConfig } from ./scripts/nodiff-core; export default defineConfig({ packages: [packages/*], tsconfig: { compilerOptions: { strict: true, target: ES2020, moduleResolution: node, }, }, dependencyPolicy: { typescript: ^5.4.0, }, generatedFiles: [ packages/*/tsconfig.json, ], });这个配置表达的意思是所有在packages/*下的子包默认使用同一套 tsconfig 基础选项TypeScript 版本必须保持在^5.4.0packages/*/tsconfig.json属于生成文件由 NoDiff 统一维护不应当被手写改动。3. 用最小示例跑通 NoDiff 的核心流程3.1 环境准备先在本地准备一个最小环境。下面这张表列出了建议版本和用途依赖建议版本用途Node.js20 LTS运行脚本和包管理pnpm9.x管理 monorepo workspaceTypeScript5.4编写脚本和子包代码glob10.x扫描子包目录minimatch9.x匹配 git diff 路径环境确认命令node -v pnpm -v tsc -v注意不同团队的 Node 版本策略可能不同。如果仓库中有多个项目建议将 Node 版本固定在根目录的 package.json 中并使用.nvmrc或Corepack管理。NoDiff 这类框架对缩进、换行、路径分隔符非常敏感Node 版本不一致本身就是生成文件产生 diff 的常见原因。3.2 创建根配置文件先创建 package.json 和 workspace 基础文件{ name: monorepo-sample, private: true, packageManager: pnpm9.12.0, scripts: { nodiff:scan: ts-node scripts/scan.ts, nodiff:check: ts-node scripts/check.ts, nodiff:affected: ts-node scripts/affected.ts }, devDependencies: { glob: ^10.4.5, minimatch: ^9.0.5, ts-node: ^10.9.2, typescript: ^5.4.5 } }pnpm-workspace.yamlpackages: - packages/*然后创建基础包mkdir -p packages/app-a/src packages/lib-b/src在packages/app-a/package.json中写入{ name: sample/app-a, version: 0.0.1, scripts: { build: tsc -p tsconfig.json } }在packages/lib-b/package.json中写入{ name: sample/lib-b, version: 0.0.1, scripts: { build: tsc -p tsconfig.json } }3.3 实现扫描逻辑NoDiff 的核心是“扫描子包 生成配置”。先实现一个极简的扫描器读取根配置并找到所有子包// scripts/nodiff-core.ts import { glob } from glob; import { readFile, writeFile } from fs/promises; import { dirname, join, relative, resolve } from path; export interface NodiffConfig { packages: string[]; tsconfig: { compilerOptions: Recordstring, unknown; }; dependencyPolicy: Recordstring, string; generatedFiles: string[]; } export function defineConfig(config: NodiffConfig): NodiffConfig { return config; } export async function loadConfig(rootDir: string): PromiseNodiffConfig { const configPath join(rootDir, nodiff.config.ts); const raw await readFile(configPath, utf-8); // 为了简单这里直接转译并加载 TS 文件 const registry require.extensions[.ts]; if (!registry) { throw new Error(当前环境未加载 ts-node无法解析 nodiff.config.ts); } const mod await import(configPath); return mod.default; } export async function scanPackages(rootDir: string, pattern: string) { const pkgFiles await glob(${pattern}/package.json, { cwd: rootDir, absolute: true, }); return pkgFiles.map((file) { const pkgDir dirname(file); return { dir: resolve(pkgDir), relativeDir: relative(rootDir, pkgDir), }; }); } export async function buildTsconfig(pkgDir: string, config: NodiffConfig) { return { extends: nitro-base/tsconfig.json, compilerOptions: { ...config.tsconfig.compilerOptions, outDir: dist, rootDir: src, }, include: [src], }; }再实现扫描脚本把每个子包应该拥有的 tsconfig 生成出来并写入磁盘// scripts/scan.ts import { join } from path; import { mkdir, readFile, writeFile } from fs/promises; import { loadConfig, scanPackages, buildTsconfig } from ./nodiff-core; export async function run() { const rootDir process.cwd(); const config await loadConfig(rootDir); const packages await scanPackages(rootDir, packages/*); for (const pkg of packages) { const tsconfigPath join(pkg.dir, tsconfig.json); const expected await buildTsconfig(pkg.dir, config); await mkdir(pkg.dir, { recursive: true }); await writeFile(tsconfigPath, ${JSON.stringify(expected, null, 2)}\n, utf-8); console.log([scan] 已生成 ${pkg.relativeDir}/tsconfig.json); } } run().catch((err) { console.error(err); process.exit(1); });这个生成逻辑的关键点在于子包的 tsconfig 不是手写的而是从根配置派生出来的。如果根配置的strict从 false 改成 true再次运行 scan所有子包的 tsconfig 会同步更新不会出现只改了一个包的情况。3.4 实现检查命令检查命令是 NoDiff 真正能进入到 CI 的功能。它不修改任何文件只比较“当前仓库里实际存在的配置”和“由根配置推导出的期望配置”// scripts/check.ts import { join } from path; import { readFile } from fs/promises; import { loadConfig, scanPackages, buildTsconfig } from ./nodiff-core; function deepEqual(a: unknown, b: unknown): boolean { return JSON.stringify(a) JSON.stringify(b); } export async function run() { const rootDir process.cwd(); const config await loadConfig(rootDir); const packages await scanPackages(rootDir, packages/*); let hasDiff false; for (const pkg of packages) { const expected await buildTsconfig(pkg.dir, config); const actualPath join(pkg.dir, tsconfig.json); let actual: unknown null; try { actual JSON.parse(await readFile(actualPath, utf-8)); } catch { hasDiff true; console.log([check] ${pkg.relativeDir}/tsconfig.json 缺失或解析失败); continue; } if (!deepEqual(expected, actual)) { hasDiff true; console.log([check] ${pkg.relativeDir}/tsconfig.json 与期望配置不一致); } } if (hasDiff) { console.error( [check] 配置存在差异。请运行 pnpm nodiff:scan 重新生成并提交生成文件。 ); process.exit(1); } console.log([check] 所有子包配置一致); } run().catch((err) { console.error(err); process.exit(1); });这样的检查逻辑有几个好处本地开发时运行一次 scan生成文件后正常提交。CI 中只运行 check不自动写文件避免 CI 环境与提交内容互相污染。如果 review 时发现某个子包的 tsconfig 被手改check 会立即报错提示重新生成。3.5 运行与预期输出初始化依赖并生成配置pnpm install pnpm nodiff:scan预期输出[scan] 已生成 app-a/tsconfig.json [scan] 已生成 lib-b/tsconfig.json此时再运行检查pnpm nodiff:check预期输出[check] 所有子包配置一致如果手动修改一个子包的 tsconfig把strict改成 false再运行pnpm nodiff:check预期输出[check] app-a/tsconfig.json 与期望配置不一致 [check] 配置存在差异。请运行 pnpm nodiff:scan 重新生成并提交生成文件。注意检查命令要同时验证“能通过”和“不能通过”两种情况。只验证能通过说明检查逻辑可能写了等于没写手动制造一次配置文件漂移再确认命令失败并给出退出码 1才算闭环。4. 关键配置项和参数的含义4.1 配置项速查表实际使用 NoDiff 时配置项的控制粒度决定了它能管到多细。下面是一张常用配置项表配置项类型默认值作用packagesstring[]无匹配子包目录的 glob 表达式tsconfig.compilerOptionsobject{}注入到所有子包 tsconfig 的编译选项dependencyPolicyobject{}指定关键依赖的允许版本范围generatedFilesstring[][]标记哪些文件应当由 NoDiff 自动生成ignoredPatternsstring[][]扫描和检查时忽略的路径pluginsstring[][]注册自定义生成器和校验器4.2 dependencyPolicy 的用法dependencyPolicy 用于防止子包依赖版本漂移。比如团队规定所有子包统一使用react18.2.0可以在配置中这样声明dependencyPolicy: { react: 18.2.0, react-dom: 18.2.0, typescript: ^5.4.0, }这个配置对 NoDiff 来说意思是“只能使用指定版本区间”。注意这里并没有使用和生产环境完全相同的语义^5.4.0表示允许 5.x 中大于等于 5.4.0 的版本但解析后的实际锁定版本仍然以锁文件为准。NoDiff 要做的是在检查时读取子包 package.json 的 dependencies、devDependencies、peerDependencies如果版本与策略不匹配就输出错误。4.3 generatedFiles 的边界generatedFiles 是一个容易产生歧义的配置。它并不是给 NoDiff 一个“随便覆盖子包文件”的权限而是告诉 NoDiff这些文件应当由根配置推导任何手写修改都算不一致。这样做的目的是把“隐式漂移”转成“显式错误”。例如generatedFiles: [ packages/*/tsconfig.json, packages/*/.eslintrc.json, packages/*/prettier.config.js, ]实际实现中NoDiff 不必真正生成这些文件它可以只做校验存在且内容与期望一致否则失败。这让配置检查与生成操作解耦CI 天然安全。4.4 参数调大或调小的影响以 ignoredPatterns 为例设置过小会把构建产物、缓存目录纳入扫描产生大量误报。设置过大会把真正需要校验的目录也漏掉降低检查价值。实际项目中建议至少忽略**/dist/**、**/.turbo/**、**/node_modules/**然后再根据仓库实际结构逐步放开。一个常见的取舍是不要把packages/*/package.json加入 generatedFiles。因为 package.json 除了依赖版本还承担了包元信息、scripts、publishConfig 等职责如果统一生成约束过强反而会限制子包的合理差异。5. 在本地开发、CI 和生产环境落地 NoDiff5.1 本地开发pre-commit 钩子本地开发时建议把 check 挂到 pre-commit 或者 lint-staged 之后。这样配置漂移不会被提交进版本库。一种轻量做法是直接在 package.json 的 scripts 中串联{ scripts: { pre-commit: pnpm nodiff:check pnpm lint:all } }使用 husky 的小配置示例npx husky add .husky/pre-commit pnpm nodiff:check开发流程变成本地修改根配置或业务代码。运行pnpm nodiff:scan重新生成配置。运行pnpm nodiff:check确认没有差异。提交时 pre-commit 再次强制检查。5.2 CI 流水线只检查不自动修复CI 中的原则是“检查失败就要人工处理而不是让脚本自动修改代码”。原因有两点CI 环境自动写文件时写入结果可能因为平台差异与本地不一致。自动修复隐藏了错误发生的原因后知后觉的人难以判断配置漂移是哪里来的。推荐 CI 步骤jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 2 - uses: pnpm/action-setupv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm nodiff:check - run: pnpm nodiff:affected --base HEAD~1fetch-depth 设置为 2是为了让 affected 命令能对比上一个提交。如果项目使用 trunk-based 开发流程可以改成对比 origin/main。5.3 生产环境的额外保障生产环境与本地环境最大的区别在于有些配置是运行时读取的不是构建时生成的。NoDiff 这类框架主要管构建期与仓库期的一致性问题生产环境还需要额外考虑配置外置化。数据库地址、缓存地址、第三方密钥不应该写死在仓库里建议使用环境变量或配置中心。日志与监控。配置生成和校验过程要输出结构化日志出现异常时能快速定位是哪个子包、哪个配置项。回滚方案。如果一次依赖版本收紧导致大量子包失败需要能快速回滚。NoDiff 的配置文件本身纳入版本控制回滚一个 commit 即可。权限与安全。不要把所有子包都交给同一个构建账号应根据包级别设置发布权限。性能与缓存。大仓库中子包数量很多扫描所有 package.json 可能耗时较长生产环境应增量分析只检查受影响的包。6. 常见问题与排查路径6.1 配置修改后不生效现象在 nodiff.config.ts 中修改了 tsconfig 的 strict重新运行 check 后仍然报旧配置。可能原因ts-node 缓存了旧的配置模块。当前终端的工作目录不是仓库根目录。package.json 中 scripts 指定的入口文件路径错误。排查方式pwd ls nodiff.config.ts pnpm nodiff:scan pnpm nodiff:check如果使用 ts-node可以尝试清理 ts-node 缓存pnpm exec ts-node --transpile-only scripts/scan.ts预防建议在脚本入口处固定 rootDir 为当前文件所在目录的上一级避免依赖用户终端目录。6.2 依赖版本误报现象子包的 package.json 中确实声明了typescript: ^5.4.0但 dependencyPolicy 始终报错。排查方式检查是否在 dependencies 和 devDependencies 中都声明了 typescript。检查 root 配置中写的是精确版本还是范围版本。检查是否因resolutions或overrides间接改写了版本。NoDiff 在设计上应当同时校验 dependencies、devDependencies、peerDependencies并在报告中说明是哪个字段不匹配避免开发者在三个字段之间来回猜测。6.3 生成文件冲突现象本地运行 scan 后git diff 显示大量子包 tsconfig 被重写且内容看起来只是引号或换行不同。主要原因JSON.stringify 的格式与手写格式不一致。使用JSON.stringify(expected, null, 2)输出的内容可能和子包原有的手写格式不同。处理方式在项目初期就确定格式化规则推荐在 scan 中统一使用JSON.stringify(..., null, 2)并保留文件末尾换行。或者使用更稳定的配置文件格式例如 YAML并统一由预ttier 处理。不要在 scan 中同时使用不同的格式化逻辑否则每次运行 diff 都会变。6.4 大仓库性能问题场景子包数量超过几百个每次全量扫描都会花很长时间。排查路径先将 glob 范围缩小确认 packages 配置是否覆盖了多余目录。查看是否读取了不必要的 package.json 字段。将检查从全量模式改成增量模式只检查 git diff 命中的子包。一个简单的 affected 命令实现思路// scripts/affected.ts import { execSync } from child_process; import { loadConfig, scanPackages } from ./nodiff-core; export async function run() { const args process.argv.slice(2); const base args[0] || HEAD~1; const changedFiles execSync(git diff --name-only ${base} HEAD) .toString() .trim() .split(\n); const rootDir process.cwd(); const config await loadConfig(rootDir); const packages await scanPackages(rootDir, packages/*); const affected packages.filter((pkg) changedFiles.some((file) file.startsWith(pkg.relativeDir)) ); for (const pkg of affected) { console.log(pkg.relativeDir); } } run().catch((err) { console.error(err); process.exit(1); });运行pnpm nodiff:affected --base HEAD~1这个实现只依赖 git diff 的文件路径与子包目录的包含关系逻辑简单也方便在 CI 中进一步扩展“只测试受影响的包”。6.5 问题排查速查表问题现象常见原因检查方式处理建议check 一直报配置不一致未运行 scan运行 scan 后 git diff 查看变更提交生成文件或修复 scan 逻辑修改根配置后无变化ts-node 缓存 rootDir 错误清理缓存并确认工作目录固定 rootDir使用 transpile-only依赖版本报错但看起来一致校验字段不对检查 dependencies/devDependencies 字段在报错信息中带出实际字段scan 生成大量格式 diff格式化逻辑与手写不一致比较生成前后的内容统一 JSON 格式或改用 YAML大仓库 check 太慢全量扫描全部包对比全量与增量耗时使用 affected 做增量检查CI 中 check 失败但本地通过环境差异导致生成文件不同在 CI 中运行 scan 看输出固定 Node 版本和包管理器版本7. 最佳实践与扩展方向7.1 可执行的最佳实践清单NoDiff 这类框架要真正在团队中生效单靠技术实现还不够还需要配套的工程约定。下面这份清单可以直接用作团队检查表根配置必须纳入版本控制不允许在本地临时修改后不提交。生成文件必须提交到版本库严禁在 CI 中重新生成后不提交。CI 中只运行 check不自动修复机器人自动提交生成文件的机制要谨慎使用。子包配置差异要在配置文件中显式声明禁止直接手改生成文件。依赖版本策略要覆盖 dependencies、devDependencies、peerDependencies 三个字段。所有 glob 路径都基于仓库根目录不依赖用户当前终端目录。Node 版本和包管理器版本写入 packageManager 字段避免锁文件被重写。每次调整根配置后先在本机运行 scan再运行 check最后查看 git diff确认只包含预期变化。把 affected 命令接入 CI减少全量检查对大型 monorepo 的负担。日志中要输出子包名、文件路径、期望值与实际值方便排错。7.2 从配置校验走向变更影响分析NoDiff 的最终价值不只是生成配置。它更重要的能力是让 monorepo 中的“变更”变得可计算、可编程。当所有子包目录、配置文件、依赖关系都集中在一个可解析的上下文中时团队可以继续扩展出更多能力根据 git diff 计算影响面生成测试执行的子集。在根配置中声明包之间的依赖关系构建时按拓扑顺序执行。在根配置中声明发布顺序包发布时只发布受影响的包。在 PR 描述中自动生成变更影响清单降低 reviewer 的认知负担。这些能力都不需要把 NoDiff 做成一个外部平台而是作为仓库内脚本和模板持续演进。这也是“lives in your monorepo”这句话的真正含义框架和仓库共同演化配置和代码一样接受评审。7.3 对团队的建议对于还在观望的团队第一个可以落地的动作不是开发复杂的生成器而是在一个足够小的 monorepo 里先跑通“根配置生成 检查 CI 拦截”。把核心链路打通后再逐步加入依赖策略、affected 增量分析和自定义插件。对于已经在用 monorepo 的团队建议优先处理两件事一是统一所有子包的配置文件生成方式二是让依赖版本策略覆盖到依赖的三个字段。这两个动作能消除大多数“无意义的 diff”也能让后续的变更影响分析建立在更干净的数据基础上。NoDiff 不是一个需要复杂部署的框架。真正需要投入的是团队对 monorepo 目录结构的共识以及对“哪些文件该由框架管理、哪些文件该留给开发者自由决定”的边界划分。边界划分清楚了diff 自然就会回到它本来的样子只承载真正的业务变更而不是把配置漂移、格式不一致和依赖版本波动混在一起交给 reviewer 处理。