Local CI兼容GitHub Actions语法全览:matrix、if表达式、secrets支持矩阵一张表看懂

原创2026-10-26 22:21:392,176 阅读

Local CI兼容GitHub Actions语法全览:matrix、if表达式、secrets支持矩阵一张表看懂

Local CI 是一款把 GitHub Actions 工作流直接跑在你本机 的工具:不重写 runner,而是用官方 runner 二进制 + 本地 API 模拟层,让你提交代码之前就能完成「运行 → 失败暂停 → 修复 → 重试」的完整闭环。本文用一张支持矩阵,帮你看懂 Local CI 对 matrix、if 表达式、secrets 等语法的支持程度,以及哪些功能需要绕道实现。

Local CI 演示:GitHub Actions 工作流在本机运行、失败暂停后重试的终端实录

为什么需要「GitHub Actions 本地运行」工具?

远程 CI 每次重试都要付一次全新运行的成本:push → 等待 → 读日志 → 再 push。Local CI 把它变成起飞前检查:

对比项 GitHub Actions 其他本地运行工具 Local CI
Runner 二进制 官方 自行重写 官方 runner
API 层 GitHub.com 兼容补丁 完整本地模拟
缓存往返 网络(数秒) 视实现而定 约 0 ms(本地文件系统)
失败后 从头再来 从头再来 暂停 → 修复 → 只重试失败步骤
需要干净 commit 是 是 否,直接跑工作树

因为执行的是官方 runner,语法兼容性来自「真身」,Local CI 只需补齐解析、上下文和 API 模拟层——这也是 compatibility.md 这份支持矩阵存在的意义。

图例:5 个状态符号,看懂支持矩阵

完整矩阵定义在 compatibility.json,渲染结果即 compatibility.md:

  • ✅ Supported —— 完整实现,行为与 GitHub Actions 一致
  • ⚠️ Partial —— 能用但有限制,注意备注
  • ❌ Not supported —— 未实现,会被跳过或报错
  • 🟡 Ignored (no-op) —— 解析不报错,但对运行无影响
  • 🚫 Not planned —— 架构上无法实现(如依赖 GitHub 侧队列的 concurrency)

matrix 支持矩阵:策略键逐个看

来自 compatibility.md 的 Strategy / Matrix 区块:

语法键 状态 说明
strategy.matrix ✅ 各键数组值完全做笛卡尔积展开
strategy.matrix.include ❌ 未实现,include 条目会被静默丢弃
strategy.matrix.exclude ❌ 同上,对象形式的条目不进解析器
strategy.fail-fast ✅ fail-fast: false 时,某个组合失败后其余组合继续跑
strategy.max-parallel ❌ 并发由 Local CI 宿主机限制(基于 CPU 核数)接管,--jobs <N> 可显式覆盖

配套的表达式上下文 matrix.*、strategy.job-total、strategy.job-index 均已支持。最简示例见 matrix.yml:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20]
    steps:
      - run: echo node ${{ matrix.node }}

💡 实用技巧:只想快速验证工作流、不想展开全部组合时,加 --no-matrix 可把所有矩阵坍缩成单个 job(每个键取第一个值)。

if 表达式支持矩阵:job 级全支持,step 级有讲究

表达式 状态 说明
success() / failure() / always() ⚠️ 按依赖波次(dependency waves)中累积的 job 状态求值;cleanup 类收尾 job 用 always() 完全可行,见 status-functions.yml
cancelled() ⚠️ 本地没有取消信号,恒返回 false,if: cancelled() 的步骤不会执行
==、!=、<、>、&&、||、!、括号 ✅ 大小写不敏感;数值强制转换遵循 GitHub Actions 语义
needs.*.outputs.* / needs.*.result ✅ 依赖 job 完成后真实解析,跨 job 传值的主力手段
steps.*.outputs.* ⚠️ 解析期为空串(步骤尚未运行),cache-hit 类引用会失效,建议改用 needs.*.outputs.*
steps.*.conclusion / outcome ❌ 步骤结果状态未暴露
纯布尔值/字符串条件(如 if: ${{ false }}) ✅ 见 skip-if.yml

要点:job 级 if 放心用;step 级 if 会原样交给官方 runner 运行时求值,但引用前置 step 输出的场景是已知短板。

secrets 支持矩阵:3 个来源按序解析

${{ secrets.FOO }} 的解析顺序(与 README.md 的 Secrets 章节一致):

优先级 来源 用法
1 .env.local-ci 文件(仓库根目录) KEY=VALUE 语法,支持 # 注释
2 Shell 环境变量 与 secret 同名即可兜底,无需额外配置
3 --github-token / LOCAL_CI_GITHUB_TOKEN 自动填充 secrets.GITHUB_TOKEN
# 方式一:写入本地 env 文件(推荐,不入库)
echo "CLOUDFLARE_API_TOKEN=xxx" >> .env.local-ci

# 方式二:内联环境变量
CLOUDFLARE_API_TOKEN=xxx local-ci run -w .github/workflows/deploy.yml

# 方式三:为 GITHUB_TOKEN 单独授权
local-ci run -w .github/workflows/ci.yml --github-token

⚠️ 注意:jobs.<id>.secrets 的 job 级继承/过滤属于 🚫 Not planned(本地无法访问 GitHub 的 secret 存储),但 with: 中直接引用 ${{ secrets.* }} 完全可用。与 secrets 相对的 vars.* 则通过 --var KEY=VALUE 或 --var-file 注入,缺失的 var 会在预检阶段直接报出清单。

其他语法速查:工作流级 / 步骤级 / 表达式

工作流级:on(push / pull_request)✅、分支与路径过滤 ✅(配合 --all 生效)、workflow_call 可复用工作流 ✅(本地 ./ 引用内联展开,远程引用需 token)、env / defaults.run.shell ✅;concurrency 🚫、tag 过滤 ❌、事件触发类(schedule 等)🟡 仅手动运行。

步骤级:run / uses(含本地 ./ action)/ with / env / shell / working-directory ✅;docker:// 镜像形式的 action ❌;timeout-minutes、continue-on-error ❌——这是有意为之:Local CI 的失败暂停模型才是处理长任务和错误的正道,硬超时会毁掉本地调试所需的容器状态。

表达式:hashFiles()、format()、toJSON / fromJSON、contains、startsWith / endsWith、join ✅;github.sha / github.repository ✅(脏工作树会合成树 SHA);github.event.* 与大部分 github.* 字段 ⚠️ 返回静态默认值;* 对象过滤运算符 ❌。

API 模拟层:actions/checkout ✅(rsync 进容器并保留本地改动)、actions/cache ⚠️(本地文件系统缓存、约 0 ms,但无按 ref 隔离)、artifact 上传下载 ✅、setup-* 工具链 ✅。

快速上手:3 步验证你的工作流

# 1. 安装依赖
git clone https://gitcode.com/gh_mirrors/ag/local-ci local-ci

# 2. 运行单个工作流
npx run-local-ci run --workflow .github/workflows/ci.yml

# 3. 失败时暂停并只重试失败步骤
npx run-local-ci run --pause-on-failure --workflow .github/workflows/ci.yml
npx run-local-ci retry --name <runner-name>

前置要求是运行中的 Docker(macOS 推荐 OrbStack);runs-on: macos-* 任务需在 Apple Silicon 上另装 tart + sshpass。

结论:哪些语法可以放心写,哪些要绕

  • ✅ 放心写:matrix 基础矩阵 + fail-fast、job 级 if + 状态函数、needs.*.outputs、secrets.* / vars.*、常用字符串与 JSON 函数
  • ⚠️ 能跑但有坑:step 级 if 引用前置输出、github.event.*、actions/cache 的跨分支隔离
  • ❌ / 🚫 要绕:include / exclude(拆成显式 job 或独立工作流)、concurrency(本地无状态队列)、docker:// action(改用仓库形式 action)

完整条目级支持矩阵以 compatibility.md 为准,机器可读版本见 compatibility.json;更多场景可参考 third-party-workflows/ 下收录的 Turborepo、Playwright 等真实第三方 workflow 作为差分解析样本。

登录后查看全文
local-ci