Act 完整指南 2026：在本機運行與除錯 GitHub Actions Workflow

2026-06-09 GitHub Actions CI/CD DevOps 自動化開源工具

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 與其他方案比較

特性	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=«redacted:ghp_…»

然後運行：

act --secret-file .env

方法二：命令列直接傳遞

act -s MY_API_KEY=your_secret_key -s GITHUB_TOKEN=«redacted:ghp_…»

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 }} 引用。

最佳實踐

在推送前始終本機測試：養成修改 workflow 後先用 Act 驗證的習慣
使用 .env 檔案管理 secret：不要硬編碼敏感資訊，將 .env 加入 .gitignore
定期更新 Act：brew upgrade act 或重新下載安裝最新版本
結合 VS Code 使用：安裝 GitHub Actions 擴充套件，在編輯器中直接預覽 workflow
CI 中保留 Act 作為可選步驟：可以在 PR 範本中提醒貢獻者本機測試

總結

Act 是 GitHub Actions 開發者的必備工具，它將原本需要幾分鐘甚至幾小時的除錯迴圈縮短到幾秒鐘。無論是簡單的單元測試 workflow，還是複雜的多階段部署流水線，Act 都能讓你在本機快速驗證。

核心優勢回顧： - ⚡ 快速迭代：本機即時運行，無需等待 GitHub 排隊 - 💰 節省成本：不消耗 GitHub Actions 分鐘數 - 🔒 安全隔離：在容器中運行，不影響主機環境 - 🛠️ 真實環境：使用與 GitHub 相同的 runner 映像，結果可靠

如果你經常編寫或維護 GitHub Actions workflow，強烈建議將 Act 加入你的工具箱。

相關連結： - Act GitHub 儲存庫 - Act 官方文件 - GitHub Actions 文件

Act 開源工具完整教學：在本機運行 GitHub Actions Workflow，無需推送到 GitHub 即可除錯 CI/CD 流水線，提升開發效率。