CI/CD / 系统课时

按文件路径过滤代码变更

按文件路径过滤代码变更

当仓库同时包含前端、后端和文档时,每次提交都运行全部工作流会浪费时间和额度。GitHub Actions 可以在事件触发层使用 paths 与 paths-ignore,让工作流只在相关文件发生变化时进入运行队列。

学习目标

  • 使用 paths 让工作流只响应指定文件或目录的变化
  • 理解 paths、paths-ignore 与分支过滤之间的组合关系
  • 避免路径规则导致必要检查意外不运行

用 paths 限定相关变更

路径过滤写在 on 对应的事件下,而不是 Job 或 Step 中。下面的工作流监听 push 和 pull_request,但只有 backend 目录或根目录的 pom.xml 发生变化时才触发。

yaml
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"

预期结果

text
修改 backend/src/... 或 pom.xml:工作流触发
只修改 docs/...:工作流不触发

这里的 backend/** 会匹配该目录下任意层级的文件。注意 push 与 pull_request 是两个独立事件,需要分别配置路径条件;在其中一个事件下配置不会自动影响另一个。

用 paths-ignore 排除无关文件

如果绝大多数文件都应该触发 CI,只有少量目录不需要运行,可以反过来使用 paths-ignore。例如仅修改 Markdown 文档或仓库文档目录时跳过测试:

yaml
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"

预期结果

text
提交只修改 docs/guide.md:工作流不触发
提交同时修改 docs/guide.md 和 src/app.js:工作流触发

paths-ignore 的含义不是“发现任意一个被忽略文件就跳过”,而是当变更文件全部落在忽略范围时才跳过。因此一次提交同时修改文档和业务代码,工作流仍会运行。

同时过滤分支和路径

路径条件可以与 branches 组合。此时不是二选一,而是两个条件都满足才触发。例如只检查进入 main 的 Pull Request,并且要求后端文件发生变化:

yaml
on:
  pull_request:
    branches:
      - main
    paths:
      - 'backend/**'

这是配置片段,需放入完整工作流文件的 on 节点,并配合 jobs 使用。生效后,目标分支不是 main,或者没有修改 backend/**,都不会启动该工作流;可以在仓库 Actions 页面通过对应提交或 Pull Request 的运行记录验证。

选择包含还是排除

规则选择取决于仓库中文件与流水线的对应关系。单体仓库只有文档不值得触发时,paths-ignore 通常更简洁;Monorepo 中每个应用有清晰目录边界时,给各工作流配置 paths 更容易控制执行范围。

如果某个工作流被配置为分支保护所要求的检查,还要谨慎使用路径过滤:被过滤掉的工作流可能不会产生预期检查结果,从而影响合并条件。路径过滤适合减少无关执行,但应先明确哪些检查必须对每个 Pull Request 都存在,再决定是否把它放到触发层过滤。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

按文件路径过滤代码变更

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通