概述
写 GitHub Actions 工作流最大的痛点是什么？改一行 YAML，push 到 GitHub，等五分钟看运行结果。失败了再改，再 push，再等。
act 解决了这个问题。它能在本地 Docker 环境中模拟 GitHub Actions 的运行，让你直接在本地跑 .github/workflows/ 里的所有 workflow。
效果：从"改代码→push→等结果"变成"改代码→act→秒出结果"。
准备工作
你需要以下条件：
- 一台 Linux VPS 或本地电脑
- Docker 已安装并运行（act 依赖 Docker）
- 一个包含
.github/workflows/的 Git 仓库 - 约 200MB 磁盘空间（用于 act 和基础镜像）
检查 Docker 是否就绪：
docker info >/dev/null 2>&1 && echo "Docker OK" || echo "请先安装 Docker"
步骤
第一步：安装 act
macOS：
brew install act
Linux（直接下载二进制）：
sudo curl -fsSL https://github.com/nektos/act/releases/latest/download/act-Linux-x86_64.tar.gz | sudo tar xz -C /usr/local/bin/
Windows（用 winget）：
winget install nektos.act
验证安装：
act --version
# 输出类似：Version: 0.2.58
第二步：准备一个测试仓库
如果你已有带 GitHub Actions 的仓库，跳到第三步。没有的话，快速建一个：
mkdir ~/test-act-repo && cd ~/test-act-repo
git init
创建 .github/workflows/ci.yml：
name: CI
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: pip install requests
- name: Run tests
run: python -c "import requests; print('requests installed:', requests.__version__)"
提交代码：
git add .
git commit -m "Initial commit"
git branch -M main
第三步：在本地运行 workflow
进入仓库目录，执行：
cd ~/test-act-repo
act push
第一次运行会拉取 ubuntu-latest 的基础 Docker 镜像，可能需要几分钟。之后每次都是秒级启动。
你会看到类似输出：
[test-act-repo/push] 🚀 Start image=ghcr.io/nektos/actrunners/act-latest:ubuntu22.04
[test-act-repo/push] 🐳 docker pull image=ghcr.io/nektos/actrunners/act-latest:ubuntu22.04
[test-act-repo/push] ⭐ Run actions/checkout@v4
[test-act-repo/push] ✅ Success - actions/checkout@v4
[test-act-repo/push] ⭐ Run Set up Python
[test-act-repo/push] ✅ Success - Set up Python
[test-act-repo/push] ⭐ Run Install dependencies
[test-act-repo/push] ✅ Success - Install dependencies
[test-act-repo/push] ⭐ Run Run tests
[test-act-repo/push] 🐳 docker exec cmd=[python -c "import requests; print('requests installed:', requests.__version__)"]
[test-act-repo/push] ✅ Success - Run tests
全部绿色，说明本地 CI 跑通了。
第四步：常用参数
列出所有可用的 workflow：
act list
指定某个 workflow 运行：
act push -W .github/workflows/ci.yml
模拟事件触发（比如模拟 pull_request）：
act pull_request
设置自定义 Docker 镜像：
act push -P ubuntu-latest=node:18-bullseye
加上 -v 参数查看详细日志：
act push -v
第五步：接入真实项目
把 act 集成到你的日常开发流程：
# 每次 git commit 后自动检查
act push --dry-run # 只模拟不执行
act push # 真正执行
也可以写个 alias 方便调用：
echo 'alias act-ci="act push"' >> ~/.bashrc
source ~/.bashrc
以后改完 workflow，直接跑 act-ci 就行。
验证
确认 act 正常工作：
# 检查版本
act --version
# 检查 Docker 连通性
act push --dry-run
# 查看本地有哪些 workflow
act list
如果 --dry-run 输出了你的 workflow 步骤列表，说明配置没问题。
常见问题
Q: act 运行很慢怎么办？
A: 第一次运行需要拉取 Docker 镜像，后续会缓存。可以在 .env 文件中配置镜像源加速下载：
echo "DOCKER_HOST=tcp://localhost:2375" >> ~/.actrc
Q: 报错 “docker: command not found”？
A: 确保 Docker 已安装且当前用户有权限运行：
sudo usermod -aG docker $USER
newgrp docker
Q: 某些 actions 在本地跑不通？
A: 部分 GitHub 专有功能（如 OIDC 令牌、GitHub API 限流）在本地不可用。可以用 --container-architecture linux/amd64 指定架构，或者用 act -s GITHUB_TOKEN="" 跳过认证相关的步骤。
Q: 如何调试 workflow 中的错误？
A: 加 -v 参数看详细日志，或者用 --reuse 复用已创建的容器，避免每次都重建：
act push -v --reuse
Q: act 支持 Windows 吗？
A: 支持，但需要 WSL2 或 Docker Desktop for Windows。原生 Windows 下 Docker 兼容性可能有问题，推荐用 WSL2 环境。
act 让 GitHub Actions 的开发效率翻了不止一倍。改完 workflow 不用 push，本地秒测。建议所有用 GitHub Actions 的项目都装上 act。
你的项目里有哪些 workflow 最耗时间？试试看 act 能不能帮到你。