GitHub Actions 怎样按路径跳过不相关工作流

如果一个仓库的文档、示例或生成目录经常变化，却不需要重新执行完整 CI，可以把过滤条件写在工作流的 on 节点，而不是等任务启动后再用 if 跳过。只想排除目录时使用 paths-ignore；需要同时包含和排除时使用 paths，并用 ! 写负向模式。

最稳妥的判断是：路径过滤决定工作流是否创建，任务级 if 只决定已经创建的 job 是否运行。先在 .github/workflows/*.yml 中选对 paths 或 paths-ignore，再检查分支、标签和必需检查状态。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax

1. 先根据排除范围选择字段

路径过滤目前主要用于 push 和 pull_request。两种字段不要在同一个事件下同时出现：只有排除规则时用 paths-ignore；只要存在“包含某目录、但排除其中子目录”的需求，就统一改用 paths。

例如，仓库只想在非文档文件变化时运行构建，可以先采用下面的最小配置：

name: CI

on:
  push:
    paths-ignore:
      # 文档改动不需要启动构建任务
      - 'docs/**'
      - '**/*.md'
  pull_request:
    paths-ignore:
      # PR 只有在包含非文档文件时才进入 CI
      - 'docs/**'
      - '**/*.md'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 运行测试
        run: go test ./... # 示例命令：替换为项目实际测试命令

2. 在 workflow 的 on 节点配置路径过滤

操作入口可以固定为：仓库首页 → Actions → 左侧选择目标 workflow → 右上角打开 workflow 文件或进入代码编辑 → 找到 on → 展开 push 或 pull_request → 在触发器下填写 paths 或 paths-ignore。GitHub 工作流文件必须放在仓库的 .github/workflows 目录。

界面中只要能确认当前编辑的是目标 YAML、事件节点没有缩进错位、过滤字段位于事件下面，就可以保存。下面的图是帮助定位字段的原创说明图，不是 GitHub 实际截图。

如果只关心一个目录，例如前端代码，可以把 paths-ignore 换成 paths：

on:
  push:
    paths:
      # 命中任一模式就允许工作流创建
      - 'web/**'
      - 'package.json'
      - 'package-lock.json'

jobs:
  web-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安装并检查前端
        run: npm ci && npm test # 安装锁定依赖后执行测试

paths 是“至少命中一个模式才运行”；它不是要求所有列出的文件都同时发生变化。模式中的 * 和 ** 用来匹配路径，写目录时通常使用 目录/** 让子目录也被覆盖。

3. 用 paths 表达“包含目录但排除子目录”

当构建只应该响应 service/，但 service/docs/ 里的文档不应触发时，不能在同一个事件里同时写 paths 和 paths-ignore。应把两类条件合并到一个 paths 列表：

on:
  pull_request:
    paths:
      # 先覆盖服务目录的全部文件
      - 'service/**'
      # 再排除服务目录中的文档子树
      - '!service/docs/**'

jobs:
  service-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 执行服务测试
        run: go test ./service/... # 只在路径过滤通过后进入这里

负向模式的顺序很重要。先有一个正向模式，再写以 ! 开头的排除模式；如果后面又写了匹配的正向模式，后者可以把之前排除的路径重新纳入。只想全部排除某些路径时，继续使用 paths-ignore 更容易读。

4. 排查“路径过滤没有生效”的几个入口

4.1 检查分支与路径是否同时满足

操作入口：workflow 文件 → on → 目标事件 → 同级查看 branches 与 paths。如果同时配置了它们，分支和路径必须都匹配。例如下面的工作流只接受 main 分支上 api/ 的改动：

on:
  push:
    branches:
      - main # 先限制目标分支
    paths:
      - 'api/**' # 再限制变更路径

jobs:
  api-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 检查 API
        run: go test ./api/... # 两个过滤条件通过后才会执行

4.2 不要用标签 push 判断路径过滤

路径过滤不会评估标签 push。如果你推送的是 tag，却期待 paths 或 paths-ignore 根据文件变化决定是否创建工作流，结果会和普通分支 push 不同。需要控制标签时，应在同一个事件下单独考虑 tags 或 tags-ignore，不要把它们和文件路径规则混为一谈。

4.3 被跳过的必需检查可能停在 Pending

操作入口：仓库 → Settings → Branches → 目标分支保护规则 → 查看必需状态检查。路径过滤跳过工作流后，关联检查可能保持 Pending；如果合并规则要求它成功，PR 可能因此无法合并。此时先确认这个检查是否真的应该对所有 PR 都是必需项，再决定调整分支保护规则或把过滤粒度改细。

保存修改后，可以按这个顺序观察：仓库 → Actions → 选择 workflow → 查看最近运行列表 → 对照变更文件和事件类型。下面的原创结果示意图只用来说明状态关系，不代表某个真实仓库已经执行。

5. 一份可直接套用的检查清单

1. workflow 文件是否位于 .github/workflows，并且编辑的是正确文件。
2. 同一个事件是否误写了 paths 和 paths-ignore 两个字段。
3. 只有排除需求时，paths-ignore 是否覆盖了所有需要忽略的目录。
4. 混合包含与排除时，paths 是否先写正向模式，再写 ! 负向模式。
5. 是否同时存在分支条件，导致路径匹配但分支不匹配。
6. 测试的是普通分支 push 或 PR，还是标签 push；后者不使用路径过滤判断。
7. PR 是否把被过滤的检查设为必需检查，导致状态停留在 Pending。

常见问题

paths-ignore 是“所有文件都忽略才跳过”吗？

是。只有当一次变更中的所有路径都匹配 paths-ignore 时，工作流才不会运行；只要有一个文件不匹配忽略模式，工作流就会创建。

可以把 paths 和 paths-ignore 同时写在 push 下吗？

不可以。想同时包含和排除时，把排除模式写进 paths，用 ! 表示负向匹配。

为什么修改 docs 后 PR 还是显示检查 Pending？

路径过滤可能跳过了工作流，但分支保护仍把对应检查列为必需项。到分支保护规则中确认该检查的必需性，或者重新设计工作流触发边界。