Skipbox

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

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 一開始是空的

依 Next.js 的 CI 建置快取指南,Next.js 會把在建置之間共用的快取存到 .next/cache,而沒有在建置之間保留它的 CI,會顯示 No Cache Detected 錯誤。它的 GitHub Actions 步驟:

- 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 指南的做法。

記憶體不足:兩種不同的錯誤

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

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

依 Next.js 的記憶體用量指南:

  • 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 不建議這樣做。

用記憶體更多的機器

每月 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 上執行的作業;在專屬機器上,還原不會覆蓋保留下來的快取。
  • 固定價格的更多核心。 編譯和靜態頁面產生都會用到它們,而分鐘數不限。

換過去只要改一行

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 上執行,可以讀取你的快取但不能修改。

詳情請見作業如何隔離。

用 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日

快取隨時熱機,CI/CD 更快

固定價格的專屬熱機 Runner

機器由 Skipbox 代管。你只要改一行。滿載使用時只要 GitHub 的 1/12。價格固定,可以整天跑。快取空間是 GitHub 的 7 倍。

  • 不需信用卡
  • 使用 GitHub 登入
  • 隨時可取消