# GitHub Actions 上的 Next.js 建置很慢或記憶體不足：快取、記憶體、Runner 規格

> GitHub Actions 上的 Next.js 建置很慢，是因為 .next/cache 沒有帶到下一次執行；記憶體不足，則是因為 webpack、型別檢查和 source map 加起來，超過了私有儲存庫 ubuntu-latest 的 8 GB。要快取什麼、哪些 Next.js 設定能減少記憶體，以及 Runner 規格：Skipbox 上 16 GB 每月 $79，32 GB 每月 $149，.next/cache 在作業之間保留，分鐘數不限。

GitHub Actions 上的 Next.js 建置，慢是一個原因，記憶體不足是另一個原因。慢，是因為 `.next/cache` 沒有帶到下一次執行：Next.js 會在建置之間重複使用這個快取，而 GitHub 託管的作業從一台新的 VM 開始，沒有快取步驟，每次建置都是冷建置（紀錄會顯示 `No Cache Detected`）。記憶體不足，是因為私有儲存庫的 `ubuntu-latest` 只有 8 GB，而大型應用程式的 webpack 編譯、型別檢查和 source map 可能會超過它。第一個問題，用 `actions/cache` 快取 `.next/cache` 來修。第二個問題，先用 Next.js 的記憶體設定（`experimental.webpackMemoryOptimizations`、不產生正式環境的 source map）；再來就是記憶體更多的機器：16 GB 或 32 GB。

Skipbox 以固定價格給建置那些記憶體：`runs-on: skipbox-8x16` 有 16 GB 和 8 vCPU，每月 $79；`skipbox-16x32` 有 32 GB 和 16 vCPU，每月 $149。在你的專屬機器上，`.next/cache` 留給下一次建置，套件快取留在磁碟上，`actions/cache` 儲存的東西在本機讀取，分鐘數不限。

- `.next/cache` 留在你的專屬機器上：下一次建置會重複使用上一次的編譯，不需要快取步驟
- 16 GB 每月 $79，32 GB 每月 $149，私有的 `ubuntu-latest` 只有 8 GB
- 套件快取留在你的機器上，快取還原讀的是它的磁碟，而不是下載

**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-nextjs-build-slow-out-of-memory-github-actions-zh-hant)

## 慢：.next/cache 一開始是空的

依 Next.js 的 [CI 建置快取指南](https://nextjs.org/docs/app/guides/ci-build-caching)，Next.js 會把在建置之間共用的快取存到 `.next/cache`，而沒有在建置之間保留它的 CI，會顯示 `No Cache Detected` 錯誤。它的 GitHub Actions 步驟：

```yaml
- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ${{ github.workspace }}/.next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
```

key 會隨每次原始碼變動而改變，所以每次執行都會儲存一個新項目，算進 GitHub 每個儲存庫 10 GB 的額度。在 Turborepo 中，把 `.next/cache` 從任務的 `outputs` 排除（`"!.next/cache/**"`），就像 [Turborepo 的 GitHub Actions 指南](https://turborepo.dev/docs/guides/ci-vendors/github-actions)的做法。

## 記憶體不足：兩種不同的錯誤

| 紀錄中 | 用完的是什麼 | 怎麼處理 |
|---|---|---|
| `JavaScript heap out of memory` | Node 自己的 heap 上限；機器還有記憶體 | 提高它：`NODE_OPTIONS=--max-old-space-size=6144`，設在機器記憶體以下 |
| `Process completed with exit code 137` | 機器的記憶體：Linux 終止了程序 | 用少一點記憶體，或換記憶體更多的機器 |

把 heap 提高到超過機器的記憶體，第一種錯誤就會變成第二種。

## 用少一點記憶體：Next.js 自己的設定

依 Next.js 的[記憶體用量指南](https://nextjs.org/docs/app/guides/memory-usage)：

- **`experimental.webpackMemoryOptimizations: true`**（v15.0.0 以上）會降低 webpack 的記憶體峰值，代價是編譯稍微變長。
- **webpack build worker** 在獨立的 Node worker 中執行編譯，能降低記憶體用量。從 v14.1.0 起，除非你有自訂的 webpack 設定，否則預設開啟；有自訂設定的話，設定 `experimental.webpackBuildWorker: true`。
- **關閉 source map：** `productionBrowserSourceMaps: false` 和 `experimental.serverSourceMaps: false`。如果建置在「Generating static pages」時記憶體用光，也加上 `enablePrerenderSourceMaps: false`。
- **測量：** `next build --experimental-debug-memory-usage`（v14.2.0 以上）會在整個建置過程中印出 heap 用量，並在接近上限時拍下 heap snapshot。
- **型別檢查：** `typescript.ignoreBuildErrors: true` 會略過型別檢查和它的記憶體，也會讓型別錯誤漏進建置。除非有另一個步驟做型別檢查，否則 Next.js 不建議這樣做。

## 用記憶體更多的機器

| Runner | CPU 和記憶體 | 誰可以用 |
|---|---|---|
| GitHub `ubuntu-latest`，私有儲存庫 | 2 顆 CPU，8 GB | 所有人 |
| GitHub `ubuntu-latest`，公開儲存庫 | 4 顆 CPU，16 GB | 公開儲存庫 |
| GitHub 大型 Runner，4 或 8 核心 | 16 GB 或 32 GB | GitHub Team 和 Enterprise Cloud 的組織，按分鐘計費（[大型 Runner](https://docs.github.com/en/actions/concepts/runners/larger-runners)） |
| Skipbox `skipbox-8x16` | 8 vCPU，16 GB | 組織和個人帳號，每月 $79 |
| Skipbox `skipbox-16x32` | 16 vCPU，32 GB | 組織和個人帳號，每月 $149 |

每月 20,000 分鐘時，GitHub 的 8 核心 Runner 是 $422，Skipbox M 是 $79；16 核心時是 $822，L 是 $149。GitHub 的金額已扣除 GitHub Team 的內含用量。

## Skipbox 為 Next.js 建置做了什麼

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

- **建置需要的記憶體**，依標籤選擇：M 有 16 GB，L 有 32 GB。把 heap 設成相應的大小，例如在 M 上用 `--max-old-space-size=12288`。
- **套件快取留在磁碟上：** `~/.npm`、pnpm store、每個工具的 `~/.cache`，以及 `setup-node` 安裝的 Node 版本。`npm ci` 會讀取它們，而不是 registry。
- **`.next/cache` 留給下一個作業。** 機器會在作業之間保留你的 checkout，其中的 `.next/cache` 也會保留，在 monorepo 裡放得再深也一樣（`apps/web/.next/cache`）。下一次 `next build` 從它開始，不需要快取步驟，也不會出現 `No Cache Detected`。`.next` 裡的其他內容和 checkout 中其他未追蹤的檔案，會在每個作業後被清除。
- **`actions/cache` 的還原讀的是這台機器。** 它儲存的東西留在機器旁邊，空間比 GitHub 每個儲存庫 10 GB 更多，還原也是一次本機讀取。`.next/cache` 的快取步驟可以留給在新 VM 上執行的作業；在專屬機器上，還原不會覆蓋保留下來的快取。
- **固定價格的更多核心。** 編譯和靜態頁面產生都會用到它們，而分鐘數不限。

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

## 換過去只要改一行

```yaml
jobs:
  build:
    runs-on: skipbox-8x16 # was ubuntu-latest
    env:
      NODE_OPTIONS: --max-old-space-size=12288
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - uses: actions/cache@v4
        with:
          path: ${{ github.workspace }}/.next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
      - run: npm ci
      - run: npx next build
```

`skipbox-8x16` 在 M 方案上執行；試用執行的是 `runs-on: skipbox`。

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

## 安全性

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

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

## 用 Next.js 建置試試看

試用免費，為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡。它執行 `runs-on: skipbox`，有 16 GB，是私有儲存庫 `ubuntu-latest` 記憶體的 2 倍：在那裡試試快取和記憶體，需要更多的建置再移到 L 方案（`skipbox-16x32`，32 GB）。

## 常見問題

### 為什麼 next build 在 GitHub Actions 上很慢？

通常是因為 .next/cache 一開始是空的。Next.js 會把建置快取存到 .next/cache，下次建置時重複使用，但 GitHub 託管的作業是一台新的 VM，所以沒有把 .next/cache 帶過去的步驟，每次建置都是冷建置，紀錄還會警告 No Cache Detected。為 .next/cache 加上 actions/cache，以 lockfile 和原始碼檔案作為 key。其餘的時間，就是在 2 顆 CPU 上的安裝和編譯。

### GitHub Actions 上的 Next.js 建置應該用多大的 Runner？

要有足以應付建置峰值的記憶體。私有儲存庫的 ubuntu-latest 只有 2 顆 CPU 和 8 GB，大型 Next.js 應用程式的 webpack 建置、型別檢查和 source map 可能會超過它。GitHub 的大型 Runner 4 核心有 16 GB，8 核心有 32 GB，只限 GitHub Team 或 Enterprise Cloud，按分鐘計費。Skipbox 在 runs-on: skipbox-8x16 上以每月 $79 給你 16 GB 和 8 vCPU，在 skipbox-16x32 上以每月 $149 給你 32 GB 和 16 vCPU。

### 怎麼修好 GitHub Actions 上 Next.js 建置的 JavaScript heap out of memory？

這個錯誤是 Node 自己的 heap 上限，不是機器的記憶體。用 NODE_OPTIONS=--max-old-space-size=<MiB> 提高它，設在機器記憶體以下。如果作業之後改以 exit code 137 結束，就是機器本身的記憶體用光了：減少建置的記憶體（experimental.webpackMemoryOptimizations、不產生正式環境的 source map），或在記憶體更多的機器上執行。

### 怎麼減少 Next.js 建置的記憶體用量？

依 Next.js 的記憶體指南：試試 experimental.webpackMemoryOptimizations（v15 以上）、保持 webpack build worker 開啟（從 v14.1.0 起，沒有自訂 webpack 設定時預設開啟）、關閉 productionBrowserSourceMaps 和 experimental.serverSourceMaps，並用 next build --experimental-debug-memory-usage 測量。用 typescript.ignoreBuildErrors 略過型別檢查可以省記憶體，但會讓型別錯誤漏進去，所以只在另一個 CI 作業有做型別檢查時才這樣做。

### Skipbox 會在作業之間保留 .next/cache 嗎？

會。你的專屬機器會在作業之間保留 checkout，其中的 .next/cache 也原地保留，不論 Next.js 把它放在哪裡（monorepo 裡是 apps/web/.next/cache），所以下一次 next build 不需要快取步驟，就從上一次的快取開始。.next 裡的其他內容和 checkout 中其他未追蹤的檔案，會在每個作業後被清除。npm 或 pnpm 的快取、setup-node 安裝的 Node 版本，以及 Docker 的層，也會留在磁碟上。為 .next/cache 設的 actions/cache 步驟可以保留：在新 VM 上執行的作業（例如來自 fork 的 Pull Request）會從它還原，而在專屬機器上，還原不會覆蓋保留下來的快取。

### 試用要花多少錢？

不用錢。試用為期 7 天或 3,000 作業分鐘，以先到者為準，不需信用卡，在 4 vCPU 和 16 GB 上執行：是私有儲存庫 ubuntu-latest 的 8 GB 的 2 倍，和 GitHub 4 核心的大型 Runner 一樣。在那裡試試快取和記憶體；需要更多的建置，就選 L 方案，並把標籤改成 skipbox-16x32（32 GB）。

更新於 2026-11-16 · https://skipbox.dev/zh-hant/guides/nextjs-build-slow-out-of-memory-github-actions
