act 介绍与选型指南

目标：讲清 act（nektos/act，在本地运行 GitHub Actions 的命令行工具）是什么、解决什么问题、核心架构与功能特性，并给出与同类 CI 工具的选型对比。本文为 A1 认知篇：全部论断基于官方文档、官方仓库与 GitHub Release/API 联网查证编写，关键论断随文标注来源与查询日期（统一为 2026-10-18），本地命令行为均已在 Ubuntu 22.04（act v0.2.89）环境实测核对。

一、环境信息

本篇为认知与选型基准篇，先固定本次介绍的信息基准，避免版本漂移导致结论失真。

官方来源清单：

• 项目主页（GitHub 仓库）：https://github.com/nektos/act
• 官方用户手册（文档站）：https://nektosact.com/
• 官方 Introduction（定位与工作原理）：https://nektosact.com/introduction.html
• 官方 Usage guide（事件/Secrets/配置文件等用法）：https://nektosact.com/usage/index.html
• 发布页：https://github.com/nektos/act/releases
• workflow 校验说明：https://nektosact.com/usage/schema.html

二、软件概述

act 是 nektos/act 项目的命令行工具，口号是「Think globally, act locally」，用于在本机直接运行 GitHub Actions 工作流（来源：官方 Introduction，https://nektosact.com/introduction.html ，查询日期 2026-10-18）。它读取仓库 .github/workflows/ 目录下已有的 GitHub Actions 工作流文件，在本机把它们真正跑起来，而不需要把代码提交（push）到 GitHub 再等待云端 Runner 执行。

官方给出两个典型动机（来源同上）：

1. 快速反馈（Fast Feedback）：修改 .github/workflows/ 后不必每次 commit/push 到 GitHub 验证，本地立刻执行；act 会把环境变量与文件系统布局配置成与 GitHub 提供的一致。
2. 本地任务运行器（Local Task Runner）：官方原话是「喜欢 make 但讨厌重复自己」——可以直接复用工作流 YAML 替代 Makefile，让「本地任务」与「云端 CI」共用同一份定义。

本次介绍的版本：act v0.2.89（2026-06-01 发布，GitHub Release 与 API 一致）。act 使用 Go 编写、编译为单一静态二进制、MIT 许可，安装与升级成本极低。

需要特别强调 act 的定位：它是本地的一次性执行器，不是常驻的 CI 服务。它没有 Web 界面、没有任务队列、没有持久 Runner 进程；每次执行都是一条命令拉起、跑完即退。因此它适合放在「开发者本机验证 workflow」这一环，而不是替代 GitHub Actions 云端或自建 CI 服务器。act 本身的安装与卸载方法，见本专栏安装篇（Ubuntu 22.04 下的 install.sh 与手动二进制两种方案、actrc 配置与常见问题均已逐条实测）。

三、核心架构

3.1 工作原理

官方 Introduction 对工作原理的描述如下（意译，来源：https://nektosact.com/introduction.html ，查询日期 2026-10-18）：运行 act 时，它读取 .github/workflows/ 中的 GitHub Actions 工作流，确定需要运行的 action 集合；随后通过 Docker API 拉取或构建所需镜像（由工作流文件定义），并根据 needs 依赖关系推导执行路径；最后用 Docker API 基于准备好的镜像，为每个 action 启动执行实例。执行期间的环境变量与文件系统布局均配置为与 GitHub 一致。

拆成三步理解：

1. 解析阶段：扫描 .github/workflows/ 下全部 YAML，解析 on: 触发事件、jobs: 依赖图（needs）、steps 步骤，并做 workflow schema 校验（校验报错样例见实测：Unknown Property stratgy 一类错误会在解析期直接暴露，详见 https://nektosact.com/usage/schema.html ）。
2. 准备阶段：按 runs-on: 标签查找平台映射（-P 参数或 actrc 配置），确定每个 Job 使用哪个平台镜像；镜像不存在时经 Docker API 拉取。
3. 执行阶段：按依赖图分 Stage 串行/并行执行；每个 Job 启动一个独立的平台镜像实例，步骤脚本在其中逐条执行，输出实时回显到终端。

3.2 执行器与平台镜像

act 自身不含运行环境，Job 的实际执行发生在「平台镜像（platform image）」拉起的执行器中。runs-on: 标签到平台镜像的映射由 -P/--platform 参数或 actrc 配置文件决定（实测配置样例：

-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04

）。首次运行且未做任何映射时，act 会给出三档默认镜像选择，以下为实测捕获的交互提示原文：

? Please choose the default image you want to use with act:
  - Large size image: ca. 17GB download + 53.1GB storage, you will need 75GB of free disk space, snapshots of GitHub Hosted Runners without snap and pulled docker images
  - Medium size image: ~500MB, includes only necessary tools to bootstrap actions and aims to be compatible with most actions
  - Micro size image: <200MB, contains only NodeJS required to bootstrap actions, doesn't work with all actions

💡 技术拓展：平台镜像的三档选择对比——

档位	体积（官方提示词口径）	内容	适用
Large	下载约 17GB + 存储 53.1GB（需 75GB 空闲）	逼近 GitHub 托管 Runner 的快照（去 snap）	对环境一致性要求极高
Medium	约 500MB 量级	仅含引导 action 所需工具，兼容大多数 action	日常本地验证（默认推荐）
Micro	小于 200MB	仅 Node.js，只够引导 action	极简步骤、资源紧张

本文档实测采用 Medium 档（ghcr.io/catthehacker/ubuntu:act-latest）：官方提示为 500MB 量级，实测拉取后本地磁盘占用约 2.31GB（含解压层差异），执行 uname -m/Node.js 类步骤均正常。

3.3 执行模型与数据流

act 把工作流解析成「Stage」拓扑：没有依赖关系的 Job 并列在同一 Stage，needs 指向的下游 Job 进入下一 Stage。实测示例仓库含三个工作流（CI 的 build→test、PR Check 的 lint、Secrets Demo 的 use-secret），act -l 输出如下（实测逐行照抄）：

Stage  Job ID      Job name    Workflow name  Workflow file  Events
0      build       build       CI             ci.yml         push
0      lint        lint        PR Check       pr.yml         pull_request
0      use-secret  use-secret  Secrets Demo   secret.yml     push
1      test        test        CI             ci.yml         push

act --graph 以字符图呈现同一拓扑（实测）：

 ╭───────╮ ╭──────╮ ╭────────────╮
 │ build │ │ lint │ │ use-secret │
 ╰───────╯ ╰──────╯ ╰────────────╯
                ⬇
             ╭──────╮
             │ test │
             ╰──────╯

工作区数据流上，act 默认把本地仓库目录直接复制进执行器的工作目录（实测日志可见 docker cp src=/opt/act-demo/. dst=/opt/act-demo），因此 actions/checkout 这类拉取代码的步骤默认被跳过、本地文件立即可用；若确要执行真实的远端 checkout，可用 --no-skip-checkout 关闭该行为（该参数定义见 act --help 原文：Use actions/checkout instead of copying local files into container）。

3.4 与 GitHub 托管 Runner 的差异

• 执行位置：GitHub 托管 Runner 在云端临时实例中执行；act 在本机经 Docker Engine 执行，速度取决于本机资源。
• 凭据：GitHub 云端自动注入 GITHUB_TOKEN；act 需要自行通过 -s GITHUB_TOKEN=... 提供（官方建议配合 GitHub CLI：act -s GITHUB_TOKEN="$(gh auth token)"，来源：https://nektosact.com/usage/index.html GITHUB_TOKEN 节，查询日期 2026-10-18）。
• 功能覆盖：act 对事件提供基础模拟，部分 GitHub 侧能力（如 Checks 上报、审批、部分 docker 上下文功能）不适用，官方设有专门的 Unsupported functionality 与 Known issues 章节说明（https://nektosact.com/not_supported.html ，查询日期 2026-10-18）。
• 事件载荷：pull_request 等事件依赖的载荷需要用 -e 提供事件 JSON 文件补全，官方文档明确「至少提供 head_ref/base_ref 才能部分模拟 pull_request 事件」（来源同 Usage guide Events 节）。

四、功能特性

以下特性均以 v0.2.89 实测核对（实测环境：Ubuntu 22.04 + Docker Engine）：

• 事件模拟：命令行直接指定事件名运行（act push、act pull_request、act schedule），无参数时默认按 push 处理（官方 Usage guide Events 节原文）；支持 --detect-event 自动选用工作流声明的首个事件，支持 -e 传入事件 JSON 完整载荷。实测：act --detect-event -n 自动选中了 PR Check 工作流的 pull_request 事件并进入 dryrun。
• 范围选择：-l 列出工作流/Job 拓扑、--graph 画依赖图、-W 指定工作流文件或目录、-j 只跑指定 Job（实测 act push -j test 会连带先跑其依赖 build）、-n 只做 dryrun 不真正执行。
• Secrets / Vars / 环境变量三通道：-s/--secret-file（默认 .secrets）注入 ${{ secrets.* }}；--var/--var-file（默认 .vars）注入 ${{ vars.* }}；--env/--env-file（默认 .env）注入进程环境变量。.env/.secrets 采用 dotenv（godotenv）格式，支持 export 前缀与多行值（来源：官方 Usage guide「.env/.secrets files structure」节）。实测：-s MY_TOKEN=q1w2e3r4-secret --var APP_MODE=debug 后工作流内取值 token length=15, env APP_MODE=debug；.env/.secrets 文件默认加载生效。
• 平台映射与多架构：-P 按 runs-on 标签映射任意平台镜像（实测把 ubuntu-22.04 从 act-22.04 临时改映射到 act-latest，镜像内 /etc/os-release 从 22.04.5 变为 24.04.4）；--container-architecture 支持指定 linux/amd64 等目标架构。
• 输出与日志：默认彩色步骤级日志（⭐ Run / ✅ Success / 🏁 Job succeeded）；--json 输出结构化 JSON 行日志；-q 静默步骤输出；-v 详细日志；-w 监视文件变化自动重跑。
• workflow 校验：--validate 校验 schema、--strict 严格模式；解析错误给出行列号与修复指引链接（实测 Unknown Property stratgy 报错并指向 https://nektosact.com/usage/schema.html ）。
• 矩阵与手动触发：--matrix 选择指定矩阵组合、--input/--input-file 为 workflow_dispatch 提供输入（官方 Usage guide「Pass Inputs to Manually Triggered Workflows」节）。
• 辅助设施：内置 artifact 服务（默认端口 34567）与缓存服务（端口默认 0 即随机）用于 actions/upload-artifact 与 actions/cache 类步骤；--action-cache-path（默认 /root/.cache/act）与 --cache-server-path（默认 /root/.cache/actcache）管理本地缓存目录。
• 自诊断：--bug-report 输出版本、构建信息、actrc 内容与 Docker Engine 探测信息，便于报障；--man-page 生成 roff 手册页。

五、快速上手（引自官方文档，非本地实测）

以下最小路径整理自官方 Introduction 与 Usage guide（来源：https://nektosact.com/introduction.html 、https://nektosact.com/usage/index.html ，查询日期 2026-10-18；命令形态均为官方文档原文）：

1. 准备一个含 .github/workflows/ 的仓库（官方 Introduction 提供了示例仓库 https://github.com/cplee/github-actions-demo 供体验）。
2. 确认本机 Docker Engine 已运行（act 的工作前提，见 3.1 节）。
3. 运行默认事件（官方：不加事件名等价于 push）：

act

4. 按事件运行（官方 Usage guide 原文命令）：

act push            # 运行所有 push 触发的工作流
act pull_request    # 运行 pull_request 触发的工作流
act schedule        # 运行 schedule 触发的工作流
act -l pull_request # 仅列出 pull_request 触发的工作流

5. 首次运行会先弹出 3.2 节的三档平台镜像选择；选择后镜像经 Docker API 拉取，随后逐步执行并实时回显每个步骤的结果。

说明：本文为认知篇，快速上手仅引官方最小命令；安装步骤与逐参数实测回显分别由安装篇与命令篇承担，本篇不重复。

六、适用场景与限制

适用场景：

• workflow 编写调试：改一步跑一步，免去「commit → push → 等云端排队 → 看日志 → 再改」的循环，这是官方宣称的第一动机（Fast Feedback）。
• 提交前自验：开发者在本地完整跑一遍将要在云端执行的 Job，提前暴露语法、依赖、脚本错误，降低云端失败率。
• 本地任务运行器：把日常构建/测试任务写成 workflow YAML，用 act 替代 Makefile，本地与 CI 共用一份定义。
• CI 故障复现：云端某 Job 失败时，用相同 workflow 在本机复现排查（配合 -e 提供真实事件载荷）。
• 受限网络/内网环境预演：无法直连 GitHub 的环境里，先本地验证 workflow 逻辑（平台镜像可从内网镜像仓库映射）。

限制：

• 必须依赖本机 Docker Engine：没有运行中的 Docker 守护进程时，执行类命令直接失败（实测报 failed to connect to the docker API at ...），act 无法脱离 Docker 运行。
• 平台磁盘开销：Medium 档平台镜像实测占用约 2.31GB，Large 档官方标称需要 75GB 空闲空间，多版本镜像并存时开销线性增长。
• 非 GitHub 环境完整复刻：官方明确 act 对事件仅提供基础模拟，且设有 Unsupported functionality 章节（如 docker context 等能力不适用）；与 GitHub 侧联动的能力（Checks/状态上报/环境审批）天然缺失。
• Secrets 需手动注入：云端自动提供的 GITHUB_TOKEN 等在本地均需显式传入，流程与云端不完全一致。
• 不是 CI 服务：无队列、无 Web 界面、无持久 Runner，不能承担团队级持续集成调度职责。

七、同类选型对比

act 的同类选型需要先分清两类问题：「本地验证 GitHub Actions workflow」与「自建一套持续集成服务」。act 属于前者；若诉求是后者，对比对象是 Forgejo Actions、Woodpecker CI、Jenkins 等自建 CI 服务。下表在统一维度下对比（act 数据为 GitHub API 实查 2026-10-18，其余工具数据来源标注于表后）：

数据来源（查询日期均为 2026-10-18）：act 与 Woodpecker、Jenkins、Gitea 的 stars/版本取自 GitHub API repos/<owner>/<repo> 与 releases 接口实查；Forgejo Actions 能力定位取自 Forgejo 官方文档（https://forgejo.org/docs/latest/user/actions/ ）；Jenkins 版本线取自 jenkins.io 发布说明（weekly 2.586、LTS 2.580）。

关键差异与选型建议：

• 只想在本地验证仓库里已有的 GitHub Actions workflow → 选 act，零服务部署、语法零转换。
• 要为团队自建一套完整 CI 且希望语法贴近 GitHub Actions → 优先评估 Forgejo Actions（若同时需要自建代码托管）或 Woodpecker CI（只需 CI、追求轻量）。
• 需要复杂的企业级流水线编排、庞大插件生态与历史积累 → Jenkins。
• 混合策略（常见于落地）：act 做开发者本机第一道验证，云端 GitHub Actions 或自建 CI 做正式执行——两者共用同一份 workflow 文件，act 的本地验证结果对云端有很高的预测性（平台镜像差异带来的环境差异除外）。

八、参考链接

• GitHub 仓库：https://github.com/nektos/act
• 官方文档站（用户手册）：https://nektosact.com/
• Introduction（定位与工作原理）：https://nektosact.com/introduction.html
• Usage guide（事件/Secrets/配置文件）：https://nektosact.com/usage/index.html
• workflow schema 校验：https://nektosact.com/usage/schema.html
• Unsupported functionality：https://nektosact.com/not_supported.html
• 发布页与版本列表：https://github.com/nektos/act/releases
• 官方示例仓库：https://github.com/cplee/github-actions-demo
• GitHub Actions 官方文档（workflow 语法参照）：https://docs.github.com/actions
• 站内相关：《GitHub Actions 常用 CLI 命令详解》（含 gh CLI 与 act 基本用法速览）；《GitHub Actions 工作流配置详解》（讲解本文所消费的 workflow YAML 语法本身）；《GitHub Actions 配置参数详解》（自托管 Runner 与 Secrets/Variables 管理参照）