# 在 GitHub Actions 上加速 pnpm 和 Turborepo monorepo（astro：528 秒變 30 秒）

> 在 GitHub Actions 上的 pnpm 和 Turborepo monorepo 中，大部分時間花在全新 VM 上的 pnpm install，以及 turbo 執行那些結果不在這台 VM 上的任務。只執行受影響的套件、給 turbo 一個快取、保留 pnpm store。或者在保留這兩者的機器上執行：astro 的 CI 從 GitHub 上的 528 秒降到 Skipbox 上的 30 秒，每月固定 $39。

在 GitHub Actions 上的 pnpm 和 Turborepo monorepo 中，慢的作業大部分時間花在兩個步驟：全新 VM 上的 `pnpm install`，以及 `turbo run build test` 執行那些結果不在這台 VM 上的任務。請依這個順序修正。只執行變更動到的套件（`turbo run build --affected`，搭配有歷史紀錄的 checkout）。給 turbo 一個比作業活得久的快取，因為它的結果存在 `.turbo/cache`，而那台機器在每個作業後都會被 GitHub 刪除：Remote Caching，或用 `actions/cache` 還原 `.turbo`。再保留 pnpm store。在 GitHub 的 Runner 上，這些快取每一個都是每個作業一次下載。在保留磁碟的機器上，它們就在那裡：astro 的 CI 作業在 GitHub 上花 528 秒，在 Skipbox 專屬機器上花 30 秒，它從 turbo 保留下來的快取重播了全部 40 個建置任務。

Skipbox 在你帳號的專屬機器上執行作業，這台機器在作業之間保留 pnpm store、工具和 checkout 的 `.turbo`，不需要遠端快取，也不需要快取 key。改一行 `runs-on: skipbox`，每月固定 $39，分鐘數不限。

- astro 的 CI：GitHub 上 528 秒，Skipbox 上 30 秒，turbo 重播了 40 個建置任務和測試任務
- pnpm store 和 turbo 的 `.turbo` 留在你的機器上：沒有遠端快取要設定，也沒有封存檔要下載
- 4 vCPU 每月 20,000 分鐘：GitHub 上要 $222，Skipbox 上是 $39

**GitHub Actions 固定價格，分鐘數不限** Skipbox 在你的專屬機器上執行 GitHub Actions 作業：每月 $39，不論執行多少分鐘。Docker 層和相依套件快取在作業之間保留，下一個作業馬上就能開始。

4 vCPU Runner，每月 20,000 分鐘: GitHub $222 → Skipbox $39. 每月省下 $183.

換過來只要改一行：`runs-on: skipbox`。

[開始 7 天免費試用](https://app.skipbox.dev/sign-in?ref=g-pnpm-turborepo-monorepo-github-actions-zh-hant)

## monorepo 作業把時間花在哪裡

| 步驟 | 在全新的 GitHub VM 上 |
|---|---|
| Checkout | 預設是淺層複製；`--affected` 需要歷史紀錄，所以要完整複製 |
| 設定 Node 和 pnpm | 要下載，除非工具快取裡有這個版本 |
| `pnpm install` | 從快取封存檔還原 store（或從 registry 下載），再為每個套件連結 `node_modules` |
| `turbo run build` | 每個任務都要執行，除非還原了 `.turbo/cache` 或有遠端快取回應 |
| `turbo run test` | 一樣，在私有儲存庫 `ubuntu-latest` 的 2 顆 CPU 上 |

## 1. 只執行有變動的部分

依 [Turborepo 的 CI 指南](https://turborepo.dev/docs/crafting-your-repository/constructing-ci)：`turbo run build --affected` 只在相對於基礎分支有變動的套件中執行任務。在 GitHub Actions 中，它在 Pull Request 上讀取 `GITHUB_BASE_REF`，在推送時讀取 `GITHUB_EVENT_PATH`。用淺層複製的話，每個套件都會被當成有變動，所以要 checkout 歷史紀錄：

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    filter: blob:none
```

`turbo query affected --packages web` 會告訴作業到底要不要執行，所以沒被動到的應用程式的作業，可以跳過它的安裝。

## 2. 給 turbo 一個比作業活得久的快取

Turborepo 把任務結果存在[機器上](https://turborepo.dev/docs/crafting-your-repository/caching)的 `.turbo/cache`。GitHub 託管作業的機器在作業結束時就被刪除，所以在 CI 上，這個快取每次都從空的開始。依 [Turborepo 的 GitHub Actions 指南](https://turborepo.dev/docs/guides/ci-vendors/github-actions)，有兩種繞過的方法：

- **Remote Caching。** 設定 `TURBO_TOKEN` 和 `TURBO_TEAM`（Vercel Remote Cache，或自架的伺服器）。每次命中都是從它下載。
- **對 `.turbo` 使用 `actions/cache`。** 以 `${{ runner.os }}-turbo-${{ github.sha }}` 為 key，加上 `restore-keys: ${{ runner.os }}-turbo-`。它每次執行都會儲存一個新項目，和儲存庫快取的其他所有東西一起，擠在 GitHub 每個儲存庫 10 GB 的額度裡。

## 3. 保留 pnpm store

`actions/setup-node` 加上 `cache: pnpm`，或對 `pnpm store path` 使用 `actions/cache`，會以 `pnpm-lock.yaml` 為 key 還原 store。它不會還原 `node_modules`，所以 pnpm 還是要連結每個套件。[pnpm 的 CI 文件](https://pnpm.io/continuous-integration)說得很直白：快取 store 不保證能讓安裝變快。在 CI 上，pnpm 會自動切換成 `--frozen-lockfile`。

## 4. 用上所有核心

turbo 會平行執行彼此獨立的任務，而每個建置或測試工具都會啟動自己的 worker，所以 monorepo 拿到多少核心就用多少。私有儲存庫的 `ubuntu-latest` 只有 2 顆。

## 每項修正在 GitHub 的 Runner 上的代價

- **Remote Caching** 是另一個服務、另一個權杖，而每次快取命中都要經過網路。
- **為 `.turbo` 用 `actions/cache`** 每次執行都會寫入一個項目，和 pnpm store、Docker 的層以及每個分支的快取，搶同一個 10 GB；7 天沒用到的項目會被移除。
- **更大的 Runner** 就是 GitHub Team 或 Enterprise Cloud 上的大型 Runner，按分鐘計費。

## 解法就是一台保留磁碟的機器

astro 自己的 CI，工作流程沒有任何修改，依[我們對真實專案的執行結果](https://skipbox.dev/zh-hant/guides/rust-cache-slow-rust-ci)：

| | GitHub（公開儲存庫，4 vCPU，16 GB） | Skipbox 專屬機器（4 vCPU） |
|---|---|---|
| 作業 | 528 秒 | **30 秒**（[31 秒](https://github.com/skipbox-dev/astro/actions/runs/43351547473)、[28 秒](https://github.com/skipbox-dev/astro/actions/runs/43351638436)） |
| 建置任務 | 執行 40 個 | 40 個都從 turbo 的快取重播 |
| 測試任務 | 執行 | 從 turbo 的快取重播 |

專屬機器保留了上一個作業的 checkout 中的 `.turbo` 和 pnpm store，所以 turbo 找到了每個任務的結果，沒有任何東西要下載。只有任務的輸入雜湊相同時，turbo 才會重播它，所以真正的 commit 會重新執行它動到的套件，其餘的則重播。

## Skipbox 保留 monorepo 的狀態

每個方案都附有一台你帳號專屬、在作業之間保留下來的機器：

- **pnpm store 會留下來**，位於 `~/.local/share/pnpm/store`，還有 npm 的快取和每個工具的 `~/.cache`。`pnpm install` 從磁碟連結，而不是下載。
- **turbo 的快取會留下來。** 當 `turbo.json` 是 turbo 2 的格式時：有 `tasks` key、沒有 `pipeline`，也沒有 `"envMode": "loose"`，checkout 最上層的 `.turbo` 會在作業之間保留下來。不需要 `TURBO_TOKEN`，也不需要快取步驟。
- **`node_modules` 會在每個作業後被刪除**，所以共用同一個 checkout 的 Node 版本矩陣，絕不會載入為另一個 Node 建置的原生擴充模組。
- **工具會留下來：** `setup-node` 安裝的 Node 版本、pnpm 本身、Docker 的映像檔和層。

S 方案的快取空間至少是 GitHub 的 7 倍。作業依標籤選擇規格：

| 標籤 | 機器 | 方案 |
|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | S，每月 $39 |
| `skipbox-8x16` | 8 vCPU · 16 GB | M，每月 $79 |
| `skipbox-16x32` | 16 vCPU · 32 GB | L，每月 $149 |

分鐘數不限。4 vCPU 每月 20,000 分鐘，GitHub 收 $222；Skipbox S 是 $39，少了 $183。

## 換過去只要改一行

```yaml
jobs:
  build:
    runs-on: skipbox # was ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: blob:none
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm turbo run build test --affected
```

1. 使用 GitHub 登入 Skipbox。
2. 安裝 Skipbox GitHub App，並選擇儲存庫。
3. 修改 `runs-on` 並推送。

快取步驟維持原樣就好；它們儲存的東西會留在機器旁邊。

## 安全性

- 機器只屬於你的帳號。其他公司的作業不會在上面執行。
- 每個作業結束後，Runner 的憑證、程序和容器都會被清除，保留下來的 checkout 中的 Git 憑證、hook 和未追蹤的檔案也是。開啟「每個作業都用新 VM」，每個作業就會改用一台全新的機器。
- 沒有寫入權限的人提交的程式碼（例如來自 fork 的 Pull Request），會在全新的 VM 上執行，可以讀取你的快取但不能修改。

詳情請見[作業如何隔離](https://docs.skipbox.dev/zh-hant/isolation)。

## 用 monorepo 試試看

試用免費，為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡。把建置作業改成 `runs-on: skipbox`，執行兩次，再把第二次執行的 install 和 turbo 那幾行（`cached` 對 `executing`）和 GitHub 上的並排比較。

## 常見問題

### 怎麼在 GitHub Actions 上加速大型 pnpm/Turborepo monorepo？

依序做三件事。只執行有變動的部分：turbo run build --affected，搭配有歷史紀錄的 checkout（fetch-depth: 0 和 filter: blob:none）。給 turbo 一個撐得過作業的快取：Turborepo 的 Remote Cache，或用 actions/cache 還原的 .turbo。再保留 pnpm store：setup-node 的 cache: pnpm，或對 store 路徑使用 actions/cache。在 GitHub 全新的 VM 上，這些每一項都是每個作業一次下載；在保留磁碟的機器上，它們本來就在。astro 的 CI 在 GitHub 上花 528 秒，在保留 turbo 快取和 pnpm store 的 Skipbox 專屬機器上花 30 秒。

### 為什麼就算快取了 store，pnpm install 在 GitHub Actions 上還是很慢？

因為還原的 store 仍然是一個在新 VM 上下載並解開的封存檔，之後 pnpm 還要為 workspace 的每個套件連結 node_modules。pnpm 自己的 CI 文件說，快取 store 不保證能讓安裝變快。已經在機器磁碟上的 store 能跳過下載；只剩下連結。

### Turborepo 的快取在 GitHub Actions 上有用嗎？

只有在快取比作業活得久時才有用。Turborepo 把任務結果存在機器上的 .turbo/cache，而 GitHub 託管作業的機器在作業結束時就消失了。所以 CI 需要 Remote Caching（TURBO_TOKEN 和 TURBO_TEAM，Vercel 的或自架的），或為 .turbo 加一個 actions/cache 步驟。在 Skipbox 的專屬機器上，turbo 2 專案的 checkout 中的 .turbo 會在作業之間保留下來，所以 turbo 不需要遠端快取就能重播沒有變動的任務。

### turbo --affected 在 GitHub Actions 上能用嗎？

能。Turborepo 在 Pull Request 上讀取 GITHUB_BASE_REF，在推送時讀取 GITHUB_EVENT_PATH，來找出要比較的基準。它需要歷史紀錄：用淺層複製的話，每個套件都會被當成有變動。在 actions/checkout 上設定 fetch-depth: 0 和 filter: blob:none。

### Skipbox 會為 Turborepo monorepo 保留什麼？

pnpm store、npm 和每個工具的快取、setup-node 安裝的工具、Docker 的層，以及當 turbo.json 是 turbo 2 格式時（有 tasks key、沒有 pipeline、不是 envMode loose），連同最上層 .turbo 的 checkout。node_modules 會在每個作業後被刪除，所以 install 會執行，但是從磁碟上的 store 安裝。只有任務的輸入雜湊相同時，turbo 才會重播它，所以一個 commit 會重新執行它動到的部分。

### 試用要花多少錢？

不用錢。試用為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡。把 monorepo 的建置作業改成 runs-on: skipbox，執行兩次，再把第二次執行的 install 和 turbo 步驟與 GitHub 上的比較。

更新於 2026-11-13 · https://skipbox.dev/zh-hant/guides/pnpm-turborepo-monorepo-github-actions
