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 会出现「命中别人产物」的诡异失败,比慢更难查。
查看「工程效能」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

Monorepo 的 CI 只跑受影响包:路径过滤漏判的四种情况 - 起航社区