act: 70K+ Star — 本地运行 GitHub Actions 的完整指南
act（nektos/act）是 CLI 工具，用 Docker 容器在本地运行 GitHub Actions。涵盖安装、设置、密钥管理、runner 镜像和生产加固。70,410 GitHub stars。
- ⭐ 70410
- 更新于 2026-08-27
act 是 CLI 工具，读取 .github/workflows/ 中的 GitHub Actions 工作流文件，用 Docker 容器在本地执行，忠实复现 GitHub Actions 运行时环境。本教程详解 act 完整设置——从安装到生产加固——让你能在推送到 GitHub 前验证每个工作流变更。
🔗 GitHub: https://github.com/nektos/act
为什么需要 act？ #
每个写过 GitHub Actions 工作流的开发者都经历过这种痛苦：你修改 .github/workflows/ci.yml，提交、推送、等待 3-5 分钟让 runner 拾取，然后看着它在第 4 步失败——因为缺少环境变量或 shell 命令中的拼写错误。反馈循环缓慢，消耗 GitHub Actions 分钟数，并用"修复 CI"消息污染提交历史。
act 解决这个问题——在 Docker 容器内本地运行 GitHub Actions 工作流，匹配 GitHub 的环境变量、文件系统布局和 runner 行为。
act 工作原理 #
act 作为本地 GitHub Actions runner 模拟器。在仓库中运行 act 时，它执行以下步骤：
- 工作流发现：扫描
.github/workflows/中的 YAML 工作流文件 - 事件解析：根据事件类型（push、pull_request 等）确定触发哪些工作流
- 依赖解析：构建作业依赖的有向无环图（DAG）
- 镜像准备：为指定 runner 拉取或构建 Docker 镜像
- 容器执行：在每个步骤内用 GitHub 兼容的环境变量和文件系统挂载运行 Docker 容器
- 产物收集：获取输出、产物和日志
Runner 镜像大小 #
act 提供三个镜像层级平衡保真度与磁盘空间：
| 镜像大小 | 下载 | 磁盘空间 | 用例 |
|---|---|---|---|
| Micro | ~50 MB | <200 MB | 仅 Node.js，快速冒烟测试 |
| Medium | ~200 MB | ~500 MB | 核心工具，适合大多数工作流 |
| Large | ~5 GB | ~18-75 GB | 完整 GitHub runner 对等，完整工具链 |
默认 Medium 镜像（catthehacker/ubuntu:act-latest）包含 Python、Node.js、Go、Ruby、Java、.NET 和常见构建工具。Large 镜像（catthehacker/ubuntu:full-*）是实际 GitHub 托管 runner 的文件系统转储，提供最接近的对等。
安装与设置 #
macOS（Homebrew） #
# 通过 Homebrew 安装 act
brew install act
# 验证安装
act --version
# act version 0.2.88
Linux（Bash 脚本） #
# 一键安装器（需要 bash 和 curl）
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
# 备选：下载预构建二进制
wget https://github.com/nektos/act/releases/download/v0.2.88/act_Linux_x86_64.tar.gz
tar xzf act_Linux_x86_64.tar.gz
sudo mv act /usr/local/bin/
Windows（Chocolatey / Scoop / WinGet） #
# Chocolatey
choco install act-cli
# Scoop
scoop install act
# WinGet
winget install nektos.act
Docker 先决条件 #
act 需要 Docker Engine API。运行前：
# 验证 Docker 正在运行
docker info
# 验证 Docker API 可访问
docker version
注意：Podman 未官方支持。对于无 root 设置或备选，使用 Docker Desktop、Rancher Desktop 或 macOS 上的 Colima。
Docker、VS Code、GitHub Enterprise 和 Make 集成 #
Docker 集成 #
act 使用 Docker 作为执行引擎。每个工作流作业在隔离容器中运行：
# 用自定义 runner 镜像运行
act -P ubuntu-latest=node:20-slim
# 指定自定义 Docker 主机（远程引擎）
export DOCKER_HOST=tcp://remote-docker:2376
act
# 用容器架构标志用于 Apple Silicon
act --container-architecture linux/amd64
VS Code 扩展（GitHub Local Actions） #
GitHub Local Actions VS Code 扩展为 act 提供 GUI：
# 从 VS Code 市场安装扩展
# 按 Cmd+Shift+P → "扩展：安装扩展" → 搜索 "GitHub Local Actions"
安装扩展后：
- 从侧边栏打开 Act 面板
- 查看
.github/workflows/中所有工作流 - 点击任何工作流在本地运行
- 在集成终端中查看实时日志
GitHub Enterprise 支持 #
act 支持私有 GitHub Enterprise Server 实例：
# 针对 GitHub Enterprise Server 运行
act --github-instance github.company.com
# 带认证
act --github-instance github.company.com -s GITHUB_TOKEN=your_token
用 act 替换 Make #
许多团队用 act 作为本地任务运行器，用 GitHub Actions 工作流替换 Makefiles：
# .github/workflows/tasks.yml
name: Local Tasks
on: workflow_dispatch
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run linter
run: npm run lint
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: npm test
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build
run: npm run build
# 本地运行任务而不是 make
act -j lint
act -j test
act -j build
基准测试 / 真实用例 #
反馈循环对比 #
| 场景 | 推送到 GitHub | 本地用 act | 节省时间 |
|---|---|---|---|
| 修复工作流中的拼写错误 | 3-5 分钟 | 15-30 秒 | 90% |
| 调试失败测试 | 5-10 分钟（多次推送） | 每次迭代 30-60 秒 | 85% |
| 测试矩阵（3 OS × 2 Node 版本） | 8-15 分钟 | 2-3 分钟 | 80% |
| 密钥/配置验证 | 3-5 分钟 | 20-40 秒 | 90% |
| 工作流语法检查 | 2-3 分钟 | 10-15 秒（dry-run） | 92% |
案例研究：减少 CI 分钟数 #
中型工程团队（25 开发者）每天运行 200 个工作流推送：
- 使用前 act：每天 ~600 次失败 CI 运行，消耗 ~3,000 GitHub Actions 分钟
- 使用后 act：开发者先在本地验证；失败 CI 运行降至每天 ~80 次
- 月节省：~66,000 GitHub Actions 分钟 = 约 $400-1,300/月（取决于 runner 类型）
高级用法 / 生产加固 #
密钥管理 #
切勿提交密钥进行测试。act 提供多种安全模式：
# 选项 1：交互式提示（推荐手动运行）
act -s MY_SECRET
# 选项 2：环境变量查找
export MY_SECRET=supersecurevalue
act -s MY_SECRET
# 选项 3：密钥文件（.secrets，与 .env 相同格式）
cat > .secrets << 'EOF'
MY_SECRET=supersecurevalue
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
EOF
act --secret-file .secrets
# 选项 4：用于 GITHUB_TOKEN（推荐只读 PAT）
act -s GITHUB_TOKEN=your_pat
立即将 .secrets 加入 .gitignore：
echo ".secrets" >> .gitignore
echo "*.secrets" >> .gitignore
模拟事件与负载文件 #
通过提供 JSON 负载文件测试依赖事件数据的工作流：
# 模拟 pull_request 事件
cat > pull-request.json << 'EOF'
{
"pull_request": {
"head": { "ref": "feature/new-login" },
"base": { "ref": "main" },
"number": 42
}
}
EOF
act pull_request -e pull-request.json
# 模拟带标签的推送
cat > tag-push.json << 'EOF'
{ "ref": "refs/tags/v1.2.3" }
EOF
act push -e tag-push.json
干跑模式 #
验证工作流语法并查看执行计划而不运行：
# 列出所有将运行的作业
act -l
# 干跑（无实际执行）
act -n
# 详细干跑
act -n -v
配置文件（.actrc） #
通过 .actrc 的项目特定配置：
# 项目根目录的 .actrc
cat > .actrc << 'EOF'
--container-architecture linux/amd64
--action-offline-mode
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--env-file .env
--secret-file .secrets
EOF
配置优先级（从高到低）：
- CLI 参数
./.actrc（项目根目录）~/.actrc（主目录）$XDG_CONFIG_HOME/act/actrc
本地运行时跳过作业/步骤 #
标记不应在本地运行的步骤：
# 在工作流文件中
jobs:
deploy:
if: ${{ !github.event.act }} # 本地跳过部署作业
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
notify:
runs-on: ubuntu-latest
steps:
- name: 本地跳过 Slack 通知
if: ${{ !env.ACT }}
run: |
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"Deployment complete"}' ${{ secrets.SLACK_WEBHOOK }}
通过事件传递 act 标志：
cat > event.json << 'EOF'
{ "act": true }
EOF
act -e event.json
产物收集 #
本地收集工作流产物：
# 指定产物服务器路径
act --artifact-server-path /tmp/artifacts
# 产物将保存到 /tmp/artifacts/<workflow>/<artifact-name>/
ls -la /tmp/artifacts/
离线模式 #
用于气隙或低带宽环境：
# 预拉取镜像
act --action-offline-mode
# 这重用本地缓存的动作仓库和 Docker 镜像
# 不从现在 GitHub 或 Docker Hub 获取
与替代品对比 #
| 特性 | act | GitHub Actions Runner | Drone CI | Jenkins |
|---|---|---|---|---|
| 本地运行 | ✅ | ❌ | ✅ | ✅ |
| Docker 原生 | ✅ | ✅ | ✅ | ✅ |
| 零配置 | ✅ | ❌ | ❌ | ❌ |
| GitHub 对等 | ✅ 高 | ✅ 完全 | ❌ | ❌ |
| 学习曲线 | 低 | 中 | 中 | 高 |
| 开源 | ✅ | ❌ | ✅ | ✅ |
| 自托管 | ✅ | ✅ | ✅ | ✅ |
常见问题 #
Q: act 需要网络连接吗？
A: 首次运行需要——act 需要拉取 Docker 镜像并从 GitHub 克隆动作仓库。之后，你可以用 --action-offline-mode 用缓存镜像和动作工作。离线前预拉取镜像：docker pull。
Q: 如何只运行工作流中的特定作业？
A: 用 -j 标志后跟工作流 YAML 中定义的作业 ID：
# 只运行 "test" 作业
act -j test
# 从特定工作流文件运行作业
act -j lint -W .github/workflows/checks.yml
Q: 我可以用 act 处理私有 GitHub 仓库或 GitHub Enterprise 吗？
A: 可以。对于私有仓库，通过 -s GITHUB_TOKEN 提供个人访问令牌。对于 GitHub Enterprise Server，用 --github-instance：
act --github-instance github.mycompany.com -s GITHUB_TOKEN=ghp_xxx
Q: 为什么工作流失败报 “MODULE_NOT_FOUND”？
A: 此错误发生在用本地动作（如 uses: ./）而无适当 checkout 时。确保你的仓库名匹配 checkout 路径。如果仓库名为 my-project，你的 checkout 步骤应包含 path: "my-project"。
Q: 如何调试失败步骤？
A: 用详细日志（-v）运行 act 并保留容器供检查：
# 详细输出
act -v
# 用详细输出运行特定作业
act -j test -v
# 容器名印在日志中；失败后检查
docker exec -it <container-name> /bin/bash
Q: act 适合运行生产 CI/CD 管道吗？ A: 不适合。act 设计用于本地开发和调试。对于生产 CI/CD，用 GitHub 托管 runner、自托管 runner 或专用 CI/CD 平台如 GitHub Actions、Drone 或 Jenkins。
Q: 如何更新 act 到最新版本？ A: 用安装时的相同包管理器：
# Homebrew
brew upgrade act
# Chocolatey
choco upgrade act-cli
# Scoop
scoop update act
# Bash 脚本（重新运行安装器）
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
结论 #
act 是 GitHub Actions 本地开发的行业标准工具。通过 70,000+ GitHub stars 和 thriving 集成生态系统，它让开发者在推送前验证工作流变更，节省 CI 分钟数并加速反馈循环。
最适合：需要本地测试 GitHub Actions 的开发者、希望减少 CI 成本的团队、气隙环境中的 CI/CD 开发。
GitHub: https://github.com/nektos/act
💬 留言讨论