路径过滤是什么
push 与 pull_request 触发可按 paths 或 paths-ignore 过滤：不相关改动的推送不创建运行，节省算力与排队时间。过滤的目的是省钱省时间，不是省检查：任何被跳过的检查都要确认它不会成为合并路径上的硬门槛。陷阱在于与分支保护的必需状态检查叠加：路径不匹配时工作流不触发，对应的必需检查永远缺席，PR 会被卡住无法合并。对策是保留一个总是运行的轻量占位作业来维持同名检查。
基本信息
| 写法 | paths: ['src/**'] 或 paths-ignore 列表 |
|---|---|
| 效果 | 不满足路径条件则不创建对应运行 |
| 陷阱 | 必需检查长期缺失导致 PR 无法合并 |
| 对策 | 保留总是运行的轻量占位作业维持检查名 |
| 覆盖范围 | 包含锁文件与工作流自身文件，避免回归漏跑 |
典型使用场景
- 文档仓库：只改 docs 目录不触发构建与测试，节省算力
- monorepo 分区：按目录过滤，改动哪个包就跑哪个包的流水线
- 微服务仓库：只改某个服务的目录，只跑该服务的构建与测试
- 大型前端：改测试文件才跑端到端，改样式只跑单元测试
- 分支保护配合：为必需检查补齐占位逻辑，保证合并不被卡
路径过滤示例
路径过滤示例
on:
pull_request:
paths:
- 'src/**' # 源码变更才触发
- 'package-lock.json' # 依赖变更也触发
- '.github/workflows/**' # 工作流自身变更触发自检场景与处理
| 场景 | 现象 | 处理 |
|---|---|---|
| 只改文档 | 必需检查一直 pending | 补占位作业或移出过滤范围 |
| 改动源码 | 正常触发全量检查 | 无需额外处理 |
| 规则过细 | 锁文件变更漏跑 | 把关键文件加入 paths |
| 占位作业 | 轻量且总是运行 | 维持必需检查名 |
把必需检查挂在可被路径跳过的流水线上，不相关的 PR 会全部卡死：要么补占位作业，要么把该检查移出过滤范围。
同一事件不能同时使用 paths 与 paths-ignore：按需要选一种写法，并用注释说明排除逻辑。
paths-ignore 适合「排除少数目录」的场景；改动范围分散时，用 paths 白名单更可控。