如何快速在本地跑通 GitHub Actions?actrun 新手完整教程

原创2026-11-03 15:44:141,718 阅读

如何快速在本地跑通 GitHub Actions?actrun 新手完整教程

还在为 GitHub Actions 的排队和慢启动烦恼吗?本文带你用 actrun(一个用 MoonBit 编写的 GitHub Actions 兼容本地 runner)在几分钟内把工作流跑起来:本地运行、查看日志、跳过无关步骤,最后再谈优化。

为什么选择 actrun 本地运行?

把 CI 搬到本地,你能获得这些好处:

  • ⚡ 秒级反馈:不用等云端队列,local 模式启动约 0.13 秒
  • 🐛 快速调试:直接读 run logs,甚至查看单条 step 日志
  • 🔄 语义一致:保持与 GitHub Actions 相同的 YAML 与上下文,本地跑通后推上去基本不用改
  • 🗂️ 可选隔离:支持 worktree、tmp、docker 等工作区模式,不污染你的工作目录

性能基准(Apple Silicon):

模式 启动耗时 写 1k 文件
local ~0.13s 52ms
nix-packages ~0.70s 47ms
apple-container ~0.93s 14ms

第一步:安装 actrun

安装方式任选其一,推荐新手直接用 npx,零安装:

# npx(无需安装)
npx @mizchi/actrun workflow run .github/workflows/ci.yml

# npm 全局安装
npm install -g @mizchi/actrun

# Docker
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/mizchi/actrun workflow run .github/workflows/ci.yml

也可以从源码构建:

git clone https://gitcode.com/gh_mirrors/ac/actrun
cd actrun
moon build src/cmd/actrun --target native

5 分钟跑通你的第一个工作流

先用仓库自带的 01-hello.yml 体验一下:

name: hello
'on': push
jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello from actrun!"

运行它就一条命令:

actrun workflow run examples/01-hello.yml

接下来是新手最常用的几个动作:

# 不真正执行,先看执行计划(推荐先跑一次确认)
actrun workflow run examples/01-hello.yml --dry-run

# 列出项目里所有工作流
actrun workflow list

# 查看历史运行与日志
actrun run list
actrun run view run-1
actrun run logs run-1 --task greet

💡 小技巧:省略 workflow run 也可以,actrun .github/workflows/ci.yml 是等价简写。

本地上下文自动填充

在普通 git 仓库里直接运行,actrun 会自动从本地仓库检测 github.repository、github.ref_name、github.sha 和 github.actor,通常不需要任何额外配置。如果你需要固定这些值(比如演示、截图场景),可以在 actrun.toml 里写 <a href="https://link.gitcode.com/i/03516361805891068d71d69aba35a145" target="_blank">local_context] 覆盖,优先级规则见 [local-context.md。

让本地更快:跳过与裁剪

先跑起来,再变快——下面这些开关就是"变快"的部分,全都无需改动工作流文件:

目标 命令 / 配置 说明
跳过本地不需要的 action --skip-action actions/checkout 可重复使用,也可写入 actrun.toml 的 local_skip_actions
只跑失败的部分 actrun ci.yml --retry 复跑时跳过已成功的 job
按文件变更跳过整个工作流 actrun ci.yml --affected HEAD~3 类似 nx / turborepo 的 affected 机制
只跑某个 job / step actrun ci.yml --job build --step test 定向调试
本地专属调试步骤 条件 if: ${{ env.ACTRUN_LOCAL }} actrun 会设置 ACTRUN_LOCAL=true

ACTRUN_LOCAL 是个非常实用的特性:本地执行时 actrun 会注入该环境变量,你可以在工作流里用它区分本地与云端。仓库里的 06-local-skip.yml 就是一个完整示例:本地跳过 checkout 和 setup-node,云端照常执行。

# 组合拳:跳过 checkout + 只跑 build job + 失败重试
actrun ci.yml --skip-action actions/checkout --job build --retry

更多参数速查请见 cheatsheet.md,--affected 的完整配置方式见 advanced-workflow.md。

常见工作流示例

仓库 examples/ 目录提供了 30+ 个可直接运行的样例,覆盖新手关心的大部分场景:

场景 示例文件
环境变量与 step 输出 02-env-and-outputs.yml
Matrix 矩阵 03-matrix.yml
Secrets 与条件分支 05-secrets.yml、09-conditional.yml
Artifacts 与 Cache 07-artifacts.yml、08-cache.yml
自定义 Action(composite / docker / node / wasm) 11-custom-actions.yml
Nix 集成 15-nix-flake.yml

Secrets 通过环境变量传入即可,无需配置文件,且会自动在日志中脱敏:

ACTRUN_SECRET_MY_TOKEN=xxx actrun workflow run .github/workflows/ci.yml

进阶工具:lint 与可视化

跑起来之后,还可以用 actrun 自带的分析命令提前发现问题:

# 类型检查表达式、检测未定义引用等(类似 actionlint)
actrun lint .github/workflows/ci.yml

# 画出 job 依赖图,直观理解执行顺序
actrun viz .github/workflows/ci.yml --mermaid

规则清单(如 undefined-context、circular-needs、script-injection 等 20 余条)详见 README.md。

总结:从跑通到变快

  1. 装:npx @mizchi/actrun 或 npm install -g @mizchi/actrun
  2. 跑:actrun workflow run .github/workflows/ci.yml
  3. 看:actrun run logs <run-id>
  4. 快:--skip-action / --retry / --affected 按需裁剪

actrun 的核心理念是"先跑起来,再谈优化":本地语义与 GitHub Actions 对齐,跑通即验证;之后用 actrun.toml 固化你的本地配置,把工作流从分钟级反馈提升到秒级反馈。更多契约与边界说明可查阅 public-api.md。

登录后查看全文
actrun