GitHub Actions 步驟怎麼平行執行？用 background、wait 與 parallel

先選對並行邊界#

GitHub 文件目前規定同一個 job 最多同時執行 10 個 background steps；超出的步驟會等待可用名額。這是 runner 的步驟並行限制，不是整個 repository 的 Actions concurrency 設定。若你要限制不同 workflow run 不要互相取消，請另外看 GitHub Actions concurrency 與部署佇列。

用 parallel 跑獨立工作#

parallel 適合一組自包含、互不寫入同一個輸出目錄的工作：

1
name: Build components
2

3
on:
4
  push:
5

6
jobs:
7
  build:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v6
11

12
      - parallel:
13
          - name: Build frontend
14
            run: npm run build:frontend
15
          - name: Build backend
16
            run: npm run build:backend
17
          - name: Build documentation
18
            run: npm run build:docs
19

20
      - name: Run integration tests
21
        run: npm test

這三個步驟會同時啟動，parallel 內建等待全部完成；其中任何一個失敗，後面的 integration tests 不應繼續。它們仍共享同一個 job 的工作目錄與環境，所以如果三個命令會改同一個檔案、搶固定 port 或共用不可並行的資料庫，就不能只因為語法短而放進同一組。

需要分開 runner、不同 Node／OS、不同權限或獨立 cache 時，應改成多個 job。parallel 不會替每個步驟建立新的 runner。

用 background 讓服務陪跑#

背景步驟適合 server、database 或測試監控器。啟動後先用獨立的健康檢查確認服務可以連線，再執行測試，最後用 cancel 收尾：

1
steps:
2
  - uses: actions/checkout@v6
3

4
  - name: Start preview server
5
    id: preview
6
    run: npm run preview
7
    background: true
8

9
  - name: Wait for preview health
10
    run: ./scripts/wait-for-preview.sh
11

12
  - name: Run browser tests
13
    run: npm run test:e2e
14

15
  - name: Stop preview server
16
    cancel: preview

background: true 只表示 job 不會在這個步驟停住，不表示 port 已經 ready。如果 server 啟動失敗，應在下一個 wait 或 wait-all 對它做同步，或讓 health check 明確失敗；不要用「測試連不上」才間接猜測 server 問題。對預期永遠不會自行結束的服務，不要把 wait: preview 放在測試之後，否則 job 會一直等到服務結束。

如果同時要啟動 database、cache 和 mock server，可以用多個 background steps，再用 wait-all 等它們結束；但服務 readiness 仍要由 health check 驗證：

1
steps:
2
  - name: Start database
3
    id: database
4
    run: docker run --rm --name ci-db postgres:15
5
    background: true
6

7
  - name: Start cache
8
    id: cache
9
    run: docker run --rm --name ci-cache redis:7
10
    background: true
11

12
  - name: Run integration tests
13
    run: npm run test:integration
14

15
  - name: Stop services
16
    cancel: database
17

18
  - name: Stop cache
19
    cancel: cache

真正的 workflow 還應處理 credentials、health check 和失敗時的 cleanup；這裡的重點是把程序生命週期寫成可審查的步驟。

需要等待輸出時用 wait#

wait 不執行命令，只等待被指定的 background step。背景步驟的 outputs 和 environment changes，也要在對應的 wait 或 wait-all 之後才交給後續步驟：

1
steps:
2
  - name: Build frontend
3
    id: frontend
4
    run: npm run build:frontend
5
    background: true
6

7
  - name: Build backend
8
    id: backend
9
    run: npm run build:backend
10
    background: true
11

12
  - name: Run lint while builds run
13
    run: npm run lint
14

15
  - name: Wait for both builds
16
    wait: [frontend, backend]
17

18
  - name: Package release
19
    run: npm run package

如果 frontend build 失敗，wait 會把失敗帶到這個同步點；不要在同步前讀取它尚未完成的 $GITHUB_OUTPUT。需要等所有正在執行的背景工作時，才用不帶參數的 wait-all。

為什麼不要把 & 當成預設解法#

舊寫法如下：

1
npm run preview &
2
npm test

foreground command 成功時，shell 可能先回傳成功，背景程序稍後才失敗；兩者的 log 也容易混在一起，清理則要自己保存 PID。若 runner 版本或既有流程真的只能使用 shell backgrounding，至少要做明確的 health check、wait 與 trap cleanup；能使用新 workflow syntax 時，讓 runner 知道哪些步驟是背景工作會更容易追查。

這和 GitHub Actions workflow execution protections 是不同層次：本文處理 job 內的步驟生命週期，權限與誰能觸發 workflow 仍要另外設定。

合併前用小型 workflow 驗證#

第一次導入時，不要直接把 production deploy 改成平行流程。可以先驗證：

1. 兩個步驟各自寫入不同檔案，從 log 確認它們確實重疊執行。
2. 讓其中一個背景步驟回傳非零，確認 wait 或 parallel 群組會失敗。
3. 讓背景 server 在測試前啟動失敗，確認 health check 能直接指出原因。
4. 檢查平行步驟沒有同時寫入同一路徑或搶同一個 port。
5. 確認測試失敗時仍會停止 server、database 和 monitor。
6. 需要隔離 runner 或矩陣版本時，改用 matrix／job，不要把隔離責任塞進 step。

把依賴關係寫出來，並行才不會只是縮短 YAML 的方式：parallel 管理一組獨立且會結束的工作，background 管理仍在運作的程序，wait／wait-all 回收結果，cancel 負責停止不再需要的服務。

常見問題#