CI/CD / 系统课时
按文件路径过滤代码变更
按文件路径过滤代码变更
当仓库同时包含前端、后端和文档时,每次提交都运行全部工作流会浪费时间和额度。GitHub Actions 可以在事件触发层使用 paths 与 paths-ignore,让工作流只在相关文件发生变化时进入运行队列。
学习目标
- 使用
paths让工作流只响应指定文件或目录的变化 - 理解
paths、paths-ignore与分支过滤之间的组合关系 - 避免路径规则导致必要检查意外不运行
用 paths 限定相关变更
路径过滤写在 on 对应的事件下,而不是 Job 或 Step 中。下面的工作流监听 push 和 pull_request,但只有 backend 目录或根目录的 pom.xml 发生变化时才触发。
name: Backend CI
on:
push:
paths:
- 'backend/**'
- 'pom.xml'
pull_request:
paths:
- 'backend/**'
- 'pom.xml'
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "Run backend checks"预期结果
修改 backend/src/... 或 pom.xml:工作流触发
只修改 docs/...:工作流不触发这里的 backend/** 会匹配该目录下任意层级的文件。注意 push 与 pull_request 是两个独立事件,需要分别配置路径条件;在其中一个事件下配置不会自动影响另一个。
用 paths-ignore 排除无关文件
如果绝大多数文件都应该触发 CI,只有少量目录不需要运行,可以反过来使用 paths-ignore。例如仅修改 Markdown 文档或仓库文档目录时跳过测试:
name: Application CI
on:
push:
paths-ignore:
- 'docs/**'
- '**/*.md'
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "Run application tests"预期结果
提交只修改 docs/guide.md:工作流不触发
提交同时修改 docs/guide.md 和 src/app.js:工作流触发paths-ignore 的含义不是“发现任意一个被忽略文件就跳过”,而是当变更文件全部落在忽略范围时才跳过。因此一次提交同时修改文档和业务代码,工作流仍会运行。
同时过滤分支和路径
路径条件可以与 branches 组合。此时不是二选一,而是两个条件都满足才触发。例如只检查进入 main 的 Pull Request,并且要求后端文件发生变化:
on:
pull_request:
branches:
- main
paths:
- 'backend/**'这是配置片段,需放入完整工作流文件的 on 节点,并配合 jobs 使用。生效后,目标分支不是 main,或者没有修改 backend/**,都不会启动该工作流;可以在仓库 Actions 页面通过对应提交或 Pull Request 的运行记录验证。
选择包含还是排除
规则选择取决于仓库中文件与流水线的对应关系。单体仓库只有文档不值得触发时,paths-ignore 通常更简洁;Monorepo 中每个应用有清晰目录边界时,给各工作流配置 paths 更容易控制执行范围。
如果某个工作流被配置为分支保护所要求的检查,还要谨慎使用路径过滤:被过滤掉的工作流可能不会产生预期检查结果,从而影响合并条件。路径过滤适合减少无关执行,但应先明确哪些检查必须对每个 Pull Request 都存在,再决定是否把它放到触发层过滤。