Monorepo 的 CI 只跑受影响包:路径过滤漏判的四种情况
给 CI 加了路径过滤后快了一倍,随后开始出现改了公共包、依赖方没跑测试就合并。本文梳理路径过滤最容易漏判的四类改动,并给出按依赖图反查受影响包的脚本写法。
给 monorepo 的 CI 加上路径过滤之后,构建时间从二十多分钟降到几分钟,然后开始零星出现「改了公共包,依赖它的服务没跑测试就直接合并了」。路径过滤的隐含假设是「改动的文件路径等于影响范围」,这个假设在 monorepo 里经常不成立。
漏判一:共享包只改了别人
最常见的一版过滤长这样:packages/api/** 触发 api 的流水线,packages/ui/** 触发 ui 的。改了 ui 里的按钮组件,依赖 ui 的 api 一条都不会跑。
正确做法是按反向依赖算:改动落在包 A,所有直接或间接依赖 A 的包都要跑。依赖图是 DAG,反向闭包才是真正的影响范围,路径匹配永远算不出来。
漏判二:根级配置不属于任何包
tsconfig.base.json、lockfile、lint 配置、构建脚本、共享的 Dockerfile——这些文件不属于任何一个包,却影响所有人。配置里如果只列了各个包的目录,改根配置时所有流水线都不触发。
处理方式两种:把根目录下的关键文件放进「总是全量跑」的列表;或者在匹配到根级文件时退化成全量构建。宁可慢一次,也别漏一次。
漏判三:diff 基准选错
用 HEAD~1 或者「最近一次提交」做对比,在多提交的 PR 上会漏掉前面几次的改动。更隐蔽的是长期分支:分支基于很旧的 base,中间 base 已经前进了很多,只比最后两次提交毫无意义。
正确基准是三点比较:merge-base(base, head) 到 head。这段差异才是这个分支真正引入的改动。
漏判四:被跳过的 required check
GitHub 分支保护里的 required status check,如果对应的 job 被 paths 过滤跳过了,PR 会一直等一个永远不会出现的结果,只能管理员强推。把路径过滤和「必过检查」组合在一起时,务必留一个总是运行、只做汇总的 job。
按依赖图算受影响包
pnpm 自带这个能力。--filter "...[<ref>]" 中的三个点表示「包含依赖它们的包」,方括号里是比较基准:
set -euo pipefail
git fetch origin main --depth=1
BASE=$(git merge-base origin/main HEAD)
echo "diff base: $BASE"
# 变更的包 + 所有依赖它们的包,只跑这些包的 test
pnpm --filter "...[${BASE}]" --if-present run test
# 只想看清单不执行
pnpm --filter "...[${BASE}]" list --depth -1
用 npm workspaces 的话,需要自己写一段遍历:读每个包 package.json 的 dependencies 与 devDependencies(带 workspace 协议的那些),建反向邻接表,从变更包做 BFS。Turbo 和 Nx 的 affected 命令本质也是同一套——建图、把文件映射到包、取反向闭包,只是把缓存也接了进去。
适用边界与常见坑
- 过滤必须留兜底。加一条每天跑一次的全量流水线,依赖图算错时不至于长期无人发现。
- 文件到包的映射要包含非源码文件:SQL 迁移、模板、静态资源、JSON 配置。只匹配
src/**一定会漏。 - 有些改动在包外却影响运行时行为:环境变量、feature flag、外部接口契约变更。这类路径过滤完全无能为力,只能靠约定和发布检查。
- CI 时间省下来了,缓存 key 也要跟着包走。用全局 key 会出现「命中别人产物」的诡异失败,比慢更难查。
正在加载评论…