如何快速在本地跑通 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）：

第一步：安装 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里写[local_context]覆盖，优先级规则见 local-context.md。

让本地更快：跳过与裁剪

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

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+ 个可直接运行的样例，覆盖新手关心的大部分场景：

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。