GitHub Actions 怎样让 job 只在条件满足时运行

GitHub Actions 让 job 只在条件满足时运行，核心就是在目标 job 下配置 if，也就是 jobs..if。例如只允许主分支的 push 进入发布 job，就把分支和事件写成一个表达式；条件不成立时，job 会在运行摘要中显示为 Skipped，不会占用该 job 的执行步骤。

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

先把条件写成可验收的规则

条件不要从按钮位置开始，而要先说清楚“什么事件、哪个分支、哪个前置结果”可以触发它。下面的例子让 publish 只在 build 成功、事件是 push 且分支是 main 时运行：

name: conditional-job

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # 拉取当前提交，供构建步骤使用
      - run: npm test # 用测试结果决定后续 job 是否有资格运行

  publish:
    needs: build # 先等待 build，失败或跳过时默认不会继续
    if: github.event_name == 'push' && github.ref == 'refs/heads/main' # 只允许主分支 push 发布
    runs-on: ubuntu-latest
    steps:
      - run: echo "publish artifact" # 这里替换为实际发布动作，并保留可核对的日志

这里的 if 可以省略 ${{ }}，GitHub Actions 会把它当作表达式求值。若表达式以 ! 开头，则应写成 if: ${{ ! startsWith(github.ref, 'refs/tags/') }} 或用引号包住，避免 YAML 把感叹号当成特殊标记。

在工作流编辑器加入 jobs.if

1. 打开仓库主页，进入 Actions，在左侧选择目标 workflow，再打开工作流文件入口。
2. 在编辑器中定位 jobs，找到需要受控的 job，例如 publish；把 if 放在该 job 下，与 needs、runs-on 对齐，不要缩进到 steps 里面。
3. 点击保存或提交变更，填写简短说明，例如“限制主分支发布”，然后回到 workflow 页面确认文件已经更新。

成功的中间状态是：目标 job 的 if 与 needs、runs-on 同级，并且编辑器能保存 YAML。若条件写到了某个 step 下，得到的只是 step 级跳过，不是整个 job 只在条件满足时启动。

用两次运行核对 Success 与 Skipped

不要只看“workflow 已通过”。先触发一次不满足条件的事件，再触发一次满足条件的事件。进入 Actions → workflow → run summary，展开 Jobs 列表，分别查看状态和条件对应关系：

条件为假时显示 Skipped 是预期结果，不要为了让整条 workflow 变绿而把它改成失败。真正需要排查的是：满足条件的运行仍然被跳过、条件字段缩进错误，或 needs 的前置 job 没有成功。

needs、always 与矩阵条件的边界

needs 描述依赖关系，if 决定当前 job 是否有资格运行，两者叠加时先看依赖是否完成，再看条件是否成立。若清理、上传诊断包这类 job 必须在前置 job 失败后仍执行，可以写：

cleanup:
  needs: [build, publish]
  if: ${{ always() }} # 即使依赖失败或跳过，也保留清理动作
  runs-on: ubuntu-latest
  steps:
    - run: echo "collect diagnostics" # 只收集诊断，不把失败伪装成成功

always() 不是“忽略所有错误”的开关；它只改变 job 是否继续进入，清理步骤仍应根据上下文判断哪些文件存在。另一个容易忽视的边界是矩阵：job 的 if 在矩阵展开前求值，不能把它当成逐个矩阵项的运行后过滤器。

常见问题

if 应该放在 steps 还是 job 下？

要控制整个 job 是否启动，放在 job 下；只控制某一个命令或 action，才放到对应 step 下。

Skipped 算失败吗？

不算。它表示条件不成立或依赖传播导致没有执行；应结合事件、分支和前置 job 的状态一起判断。

为什么写了 always() 仍然没有发布？

always() 只绕过依赖结果造成的默认跳过，不能修复 YAML 缩进、权限、runner 不可用或发布步骤自身的错误。