github actions 可通过 on.push.paths 或 paths-ignore 精准按文件路径变更触发工作流：paths 为白名单（仅匹配文件触发），paths-ignore 为黑名单（匹配文件不触发），二者不可共存，且仅对 push 和 pull_request 事件生效；路径须相对于仓库根目录，支持 **（任意层级）和 *（当前目录），区分大小写，修改/新增/删除均触发。
GitHub Actions 可以精准地根据文件路径的变更来触发工作流，避免无关修改导致整条流水线无谓运行。关键在于正确配置 on.push.paths（或 paths-ignore），但要注意它只对 push 和 pull_request 事件生效，且路径匹配逻辑有严格规则。
路径触发的核心写法
paths 是白名单机制：只有匹配到的文件变更才会触发工作流；paths-ignore 是黑名单机制：匹配到的文件变更将被排除，不触发。
两者不能同时出现在同一个事件配置中（会报错），必须二选一。
示例（只在 src/ 或 config/ 下文件变动时触发）：
on:
push:
branches: [main]
paths:
- "src/**"
- "config/*.yml"
- "package.json"
示例（忽略文档和 Markdown 文件，其余都触发）：
on:
push:
branches: [main]
paths-ignore:
- "docs/**"
- "**.md"
- ".gitignore"
路径匹配的几个关键细节
-
路径是相对于仓库根目录的，不是相对于
.github/workflows/ - 使用
**表示任意层级的子目录（如src/**/test.js匹配src/utils/test.js和src/api/v1/test.js） - 单个
*只匹配当前目录下的文件（如src/*.js不匹配src/lib/helper.js） - 路径区分大小写（
README.md≠readme.md） - 修改、新增、删除文件都会触发匹配（Git 的 diff 决定是否命中）
常见踩坑点
-
on: workflow_dispatch不支持paths或paths-ignore—— 手动触发永远生效，无法按路径过滤 -
pull_request的paths匹配的是 PR 中实际变更的文件（即git diff --name-only origin/main...HEAD的结果），不是目标分支的全量文件 - 如果用
paths但没写任何有效模式（比如留空或全写错），工作流将永远不会被 push 触发 -
.yml文件自身改动（如改ci.yml）不会触发该工作流——GitHub 不会用自身变更去触发自己
实用建议
- 开发阶段可先用宽泛路径（如
src/**），上线后再收敛 - 多个相关路径建议拆成独立条目，比写复杂 glob 更易读、更可靠
- 配合
act本地测试时，需用--job指定作业，并手动模拟变更文件（act -j build --input files="src/index.js"） - 若需更细粒度控制（比如仅当模型权重文件
.pt更新才跑推理验证），直接用paths锁定后缀即可：
on:
push:
paths:
- "**.pt"
- "models/**.bin"
