搬瓦工 VPS 使用 Act 本地运行 GitHub Actions 教程

Act 是一款开源工具，可以在本地环境中运行 GitHub Actions Workflow，无需将代码推送到 GitHub 即可测试和调试 CI/CD 流程。Act 使用 Docker 容器模拟 GitHub Actions 的运行环境，支持大部分官方 Actions 和自定义步骤。对于频繁迭代 Workflow 配置的开发者，Act 能节省大量等待时间和 GitHub Actions 分钟数配额。本教程将介绍如何在搬瓦工 VPS 上安装和使用 Act。部署前请确保已安装好 Docker。

一、Act 核心优势

本地执行：在 Docker 容器中模拟 GitHub Actions Runner 环境。
快速迭代：修改 Workflow 后秒级反馈，无需等待 GitHub 排队。
离线运行：大部分 Workflow 可以在无外网的环境中测试。
Secret 支持：从本地 .secrets 文件或环境变量加载敏感信息。
事件模拟：可模拟 push、pull_request、schedule 等各种触发事件。

二、安装 Act

# 通过官方脚本安装
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | bash

# 手动安装
wget https://github.com/nektos/act/releases/latest/download/act_Linux_x86_64.tar.gz
tar xzf act_Linux_x86_64.tar.gz -C /usr/local/bin/

# 验证安装
act --version

三、配置 Runner 镜像

# 首次运行时 Act 会提示选择镜像大小
# Micro  (~200MB) - 最小，缺少很多工具
# Medium (~500MB) - 适合大部分场景
# Large  (~18GB)  - 最接近 GitHub 真实环境

# 创建配置文件指定默认镜像
cat > ~/.actrc <<'EOF'
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04
--container-daemon-socket /var/run/docker.sock
EOF

# 预拉取镜像加速首次运行
docker pull catthehacker/ubuntu:act-latest

四、基本使用

cd /opt/my-github-project

# 列出所有 Workflow 和 Job
act -l

# 运行默认事件（push）的所有 Workflow
act

# 运行特定事件
act pull_request
act workflow_dispatch

# 运行特定 Job
act -j build
act -j test

# 运行特定 Workflow 文件
act -W .github/workflows/ci.yml

# 详细输出
act -v

五、Secret 和环境变量

# 创建 Secret 文件（不要提交到 Git）
cat > .secrets <<'EOF'
DEPLOY_SSH_KEY=your_ssh_private_key_content
API_TOKEN=your_api_token_2026
DOCKER_PASSWORD=your_docker_pass
NPM_TOKEN=your_npm_token
EOF

# 使用 Secret 文件运行
act --secret-file .secrets

# 命令行传入单个 Secret
act -s MY_SECRET=secret_value

# 环境变量
cat > .env <<'EOF'
NODE_ENV=test
CI=true
EOF
act --env-file .env

六、调试技巧

# 模拟运行（不实际执行命令）
act -n

# 自定义事件 Payload
cat > event.json <<'EOF'
{
  "pull_request": {
    "number": 42,
    "head": {"ref": "feature-branch"},
    "base": {"ref": "main"}
  }
}
EOF
act pull_request -e event.json

# 使用 --reuse 复用容器加速调试
act -j build --reuse

# 在步骤之间保留工作目录
act --bind

七、示例 Workflow 测试

# .github/workflows/ci.yml
name: CI Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - run: npm run build
      - run: echo "Build complete"

# 本地测试
act -l                    # 列出 Jobs
act -j test               # 只运行测试
act push                  # 模拟 push 事件
act pull_request          # 模拟 PR 事件

八、Docker-in-Docker

# 如果 Workflow 中需要使用 docker 命令
act --container-daemon-socket /var/run/docker.sock --bind --privileged

# 或在 .actrc 中配置
echo "--privileged" >> ~/.actrc

九、常见问题

某些 Actions 不兼容

部分 GitHub 特有功能（OIDC Token、Artifacts v4 等）在 Act 中不可用。可以用 if: ${{ !env.ACT }} 条件跳过本地不支持的步骤。

镜像拉取失败

# 提前拉取需要的镜像
docker pull catthehacker/ubuntu:act-latest
docker pull node:20-alpine
docker pull golang:1.22

权限问题

# 确保 Docker socket 可访问
ls -la /var/run/docker.sock
chmod 666 /var/run/docker.sock

总结

Act 是 GitHub Actions 开发者的必备调试工具，在搬瓦工 VPS 上运行能获得稳定的 Docker 环境和快速反馈。如果需要搭建完整的自托管 CI/CD 系统，推荐 Woodpecker CI。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。