Act 是什么？

Act 是一个开源命令行工具，让你在本地运行 GitHub Actions Workflow，无需将代码推送到 GitHub 即可测试和调试 CI/CD 流水线。

对于经常编写 GitHub Actions 的开发者来说，这是一个效率神器：

  • 快速迭代：修改 workflow 后立刻在本地运行，不用等待 GitHub 排队和执行
  • 节省资源：不消耗 GitHub Actions 分钟数（尤其是私有仓库）
  • 离线调试：在没有网络连接的环境下也能测试 workflow
  • 安全测试：在隔离环境中验证 workflow 的安全性，避免意外执行危险操作

为什么需要 Act？

GitHub Actions 是强大的 CI/CD 平台，但调试 workflow 有一个痛点：

修改 .github/workflows/test.yml 
→ git commit 
→ git push 
→ 等待 GitHub 排队（可能几分钟到几小时）
→ 查看日志发现错误
→ 重复上述步骤

这个循环非常耗时。有了 Act，你可以：

修改 .github/workflows/test.yml 
→ act -j test    # 本地立即运行
→ 查看输出，修复问题
→ 再次运行，确认无误后再推送

效率提升至少 10 倍。

Act vs 其他方案

特性 Act GitHub Web UI Docker Compose 模拟
运行速度 ⚡ 本地即时 🐌 需排队等待 ⚡ 本地但配置复杂
真实性 ✅ 使用真实 GitHub Actions runner 镜像 ✅ 完全真实 ❌ 需要手动模拟
成本 💰 免费（本地运行） 💰 消耗 Actions 分钟数 💰 免费
易用性 ✅ 一条命令 ✅ 图形界面 ❌ 配置繁琐
离线支持 ✅ 完全离线 ❌ 需要网络 ✅ 可离线

安装 Act

macOS（Homebrew）

brew install act

Linux

Ubuntu/Debian：

curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Arch Linux：

yay -S act
# 或
paru -S act

Windows

Chocolatey：

choco install act-cli

Scoop：

scoop install act

验证安装

act --version
# 输出类似：act version 0.2.x

快速上手：运行第一个 Workflow

前提条件

确保你的项目根目录有 .github/workflows/ 目录，里面包含至少一个 workflow 文件（.yml 或 .yaml）。

列出可用的 Workflow

cd /path/to/your/project
act -l

输出示例：

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    Test      CI             ci.yml         push,pull_request
0      build   Build     CI             ci.yml         push,pull_request

运行指定 Job

# 运行名为 test 的 job
act -j test

# 运行所有 job
act

# 运行特定事件触发的 workflow（如 pull_request）
act pull_request

首次运行的注意事项

第一次运行时，Act 会下载必要的 Docker 镜像（通常是 catthehacker/ubuntu:act-latest），这可能需要几分钟时间。后续运行会使用缓存，速度更快。

INFO[0000] Using docker host 'unix:///var/run/docker.sock'
INFO[0000] Pulling image 'catthehacker/ubuntu:act-latest'
...

进阶用法

1. 使用不同的 Runner 镜像

Act 默认使用 Ubuntu 镜像，但你可以通过 -P 参数指定不同的平台：

# 使用 Ubuntu 22.04
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# 使用 Ubuntu 20.04
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# 使用轻量级镜像（更快，但功能有限）
act -P ubuntu-latest=node:16-buster-slim

2. 传递 Secret 和环境变量

很多 workflow 依赖 secret（如 API 密钥、Token）。你可以通过 .env 文件或命令行传递：

方法一：使用 .env 文件

在项目根目录创建 .env 文件：

MY_API_KEY=your_secret_key
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

然后运行：

act --secret-file .env

方法二：命令行直接传递

act -s MY_API_KEY=your_secret_key -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. 并行执行多个 Job

如果你的 workflow 有多个独立的 job，可以使用 --parallel 加速：

act --parallel

4. 干跑模式（Dry Run）

只打印将要执行的步骤，不实际运行：

act -n

5. 自定义工作目录

如果 workflow 依赖特定的目录结构，可以绑定挂载：

act --bind

这会将当前目录挂载到容器内，使文件修改实时生效。

实战案例

案例 1：调试 Node.js 项目的 CI

假设你有一个 Node.js 项目，workflow 如下：

# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

在本地运行：

act -j test

如果测试失败，Act 会显示完整的日志输出，方便定位问题。

案例 2：测试多版本 Python 矩阵

# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

运行所有 Python 版本的测试：

act -j test

Act 会自动遍历矩阵中的所有组合并依次执行。

案例 3：调试 Docker 构建

# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

在本地运行前，确保 Docker daemon 正在运行：

# 检查 Docker 是否可用
docker info

# 运行 workflow
act -j build

常见问题排查

问题 1：权限错误

现象： permission denied while trying to connect to the Docker daemon socket

解决：

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER
# 重新登录或运行 newgrp docker

或者使用 sudo 运行 Act（不推荐）：

sudo act

问题 2：内存不足

现象： 大型 workflow 运行时 OOM（Out of Memory）

解决： 限制并发 job 数量

act --max-parallel 1

问题 3：Action 找不到

现象： unable to find action 'actions/checkout@v4'

解决： Act 需要从 GitHub 下载 action，确保网络连接正常。对于私有 action，需要设置 GITHUB_TOKEN。

问题 4：环境变量未生效

现象： workflow 中引用的环境变量为空

解决： 确保通过 --secret-file 或 -s 正确传递了变量，并在 workflow 中使用 ${{ env.VAR_NAME }} 或 ${{ secrets.VAR_NAME }} 引用。

最佳实践

  1. 在推送前始终本地测试：养成修改 workflow 后先用 Act 验证的习惯
  2. 使用 .env 文件管理 secret：不要硬编码敏感信息，将 .env 加入 .gitignore
  3. 定期更新 Act：brew upgrade act 或重新下载安装最新版本
  4. 结合 VS Code 使用：安装 GitHub Actions 扩展，在编辑器中直接预览 workflow
  5. CI 中保留 Act 作为可选步骤：可以在 PR 模板中提醒贡献者本地测试

总结

Act 是 GitHub Actions 开发者的必备工具，它将原本需要几分钟甚至几小时的调试循环缩短到几秒钟。无论是简单的单元测试 workflow，还是复杂的多阶段部署流水线，Act 都能让你在本地快速验证。

核心优势回顾： - ⚡ 快速迭代：本地即时运行，无需等待 GitHub 排队 - 💰 节省成本：不消耗 GitHub Actions 分钟数 - 🔒 安全隔离：在容器中运行，不影响主机环境 - 🛠️ 真实环境：使用与 GitHub 相同的 runner 镜像，结果可靠

如果你经常编写或维护 GitHub Actions workflow，强烈建议将 Act 加入你的工具箱。

相关链接： - Act GitHub 仓库 - Act 官方文档 - GitHub Actions 文档