# GitHub Actions 中 Next.js 构建慢或内存不足：缓存、内存、运行器规格

> 当 .next/cache 没有带到下一次运行时，GitHub Actions 中的 Next.js 构建就会慢；一旦 webpack、类型检查和 source map 加起来，在私有仓库 8 GB 的 ubuntu-latest 上就会内存不足。本文讲该缓存什么、哪些 Next.js 设置能减少内存，以及运行器规格：在 Skipbox 上，16 GB 每月 $79，或者 32 GB 每月 $149，.next/cache 在作业之间保留，分钟数不限。

GitHub Actions 中的 Next.js 构建，慢有一个原因，内存不足有另一个原因。慢，是因为 `.next/cache` 没有带到下一次运行：Next.js 在两次构建之间复用这个缓存，而 GitHub 托管的作业在一台新虚拟机上启动，没有缓存步骤的话，每次构建都是冷构建（日志会显示 `No Cache Detected`）。内存不足，是因为私有仓库的 `ubuntu-latest` 只有 8 GB，一个大型应用的 webpack 编译、类型检查和 source map 可能超过这个量。第一个问题用 `.next/cache` 上的 `actions/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 运行器，每月 2万分钟: 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-hans)

## 慢：.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') }}-
```

源代码每改一次，键就变一次，所以每次运行都保存一个新条目，占用 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 自己的堆上限；机器还有内存 | 提高它：`NODE_OPTIONS=--max-old-space-size=6144`，设在机器内存以下 |
| `Process completed with exit code 137` | 机器的内存：Linux 终止了进程 | 少用内存，或者换一台内存更大的机器 |

把堆上限提到超过机器内存，第一种错误就会变成第二种。

## 少用内存：Next.js 自己的设置

根据 Next.js 的[内存使用指南](https://nextjs.org/docs/app/guides/memory-usage)：

- **`experimental.webpackMemoryOptimizations: true`**（v15.0.0 及以上）降低 webpack 的内存峰值，编译时间会稍长一些。
- **webpack 构建工作进程**：在一个单独的 Node 工作进程中运行编译，从而降低内存。自 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 及以上）在整个构建过程中打印堆的使用情况，并在接近上限时生成堆快照。
- **类型检查**：`typescript.ignoreBuildErrors: true` 跳过类型检查和它占用的内存，也会让类型错误混进构建。除非另有步骤做类型检查，Next.js 不建议这样做。

## 用一台内存更大的机器

| 运行器 | CPU 和内存 | 谁能用 |
|---|---|---|
| GitHub `ubuntu-latest`，私有仓库 | 2 个 CPU，8 GB | 所有人 |
| GitHub `ubuntu-latest`，公开仓库 | 4 个 CPU，16 GB | 公开仓库 |
| GitHub 大型运行器，4 或 8 核 | 16 GB 或 32 GB | GitHub Team 和 Enterprise Cloud 上的组织，按分钟计费（[大型运行器](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 |

每月 2万分钟时，GitHub 的 8 核运行器是 $422，Skipbox M 是 $79；16 核时，是 $822 对 L 的 $149。GitHub 的金额已减去 GitHub Team 包含的用量。

## Skipbox 为 Next.js 构建做了什么

每个套餐都附带你账号的专属机器，在作业之间一直保留：

- **构建需要的内存**，按标签选：M 为 16 GB，L 为 32 GB。相应地设置堆上限，比如在 M 上用 `--max-old-space-size=12288`。
- **包缓存留在磁盘上**：`~/.npm`、pnpm store、各个工具的 `~/.cache`，以及 `setup-node` 安装的 Node 版本。`npm ci` 读取它们，而不是访问注册表。
- **`.next/cache` 留给下一个作业**：机器在作业之间保留你的检出目录，其中的 `.next/cache` 也保留，在 monorepo 里放得再深也一样（`apps/web/.next/cache`）。下一次 `next build` 从它开始，不需要缓存步骤，也不会出现 `No Cache Detected`。`.next` 里的其他内容和检出目录中其他未跟踪的文件，在每个作业后都会被清理。
- **`actions/cache` 的恢复读的是这台机器**：它保存的东西就放在机器旁边，空间比 GitHub 每个仓库 10 GB 更大，恢复是本地读取。`.next/cache` 的缓存步骤可以留给在新虚拟机上运行的作业；在专属机器上，恢复不会覆盖保留下来的缓存。
- **以固定价格获得更多核心**：编译和静态页面生成都会用上它们，分钟数不限。

| 标签 | 机器 | 套餐 |
|---|---|---|
| `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 应用，并选择仓库。
3. 修改 `runs-on` 并推送。

## 安全

- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后，运行器的凭据、进程和容器都会被清除，保留的检出目录中的 git 凭据，以及 `.next/cache` 这类构建缓存以外的未跟踪文件也一样。开启“每个作业用新虚拟机”后，每个作业改在一台新机器上运行。
- 没有写入权限的人提交的代码（例如来自复刻的拉取请求）在一台新的虚拟机上运行，它能读取你的缓存，但不能修改。

详情见[作业如何隔离](https://docs.skipbox.dev/zh-hans/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 托管的作业是一台新虚拟机，所以没有一个把 .next/cache 带过来的步骤，每次构建都是冷构建，日志会提示 No Cache Detected。为 .next/cache 加上 actions/cache，以锁文件和源文件作为键。剩下的时间花在安装和 2 个 CPU 上的编译。

### GitHub Actions 中的 Next.js 构建应该用多大规格的运行器？

内存要够构建的峰值用。私有仓库的 ubuntu-latest 是 2 个 CPU、8 GB，一个大型 Next.js 应用的 webpack 构建、类型检查和 source map 可能超过这个量。GitHub 的大型运行器 4 核有 16 GB，8 核有 32 GB，只在 GitHub Team 或 Enterprise Cloud 上提供，按分钟计费。Skipbox 在 runs-on: skipbox-8x16 上给 16 GB 和 8 vCPU，每月 $79；在 skipbox-16x32 上给 32 GB 和 16 vCPU，每月 $149。

### 怎样解决 GitHub Actions 上 Next.js 构建的 JavaScript heap out of memory？

这个错误是 Node 自己的堆上限，而不是机器的内存。用 NODE_OPTIONS=--max-old-space-size=<MiB> 提高它，设在机器内存以下。如果作业随后改为以退出码 137 结束，说明是机器本身内存耗尽了：减少构建的内存（experimental.webpackMemoryOptimizations，生产环境不生成 source map），或者在内存更大的机器上运行。

### 怎样减少 Next.js 构建的内存使用？

根据 Next.js 的内存指南：试试 experimental.webpackMemoryOptimizations（v15 及以上），保持 webpack 构建工作进程开启（自 v14.1.0 起，没有自定义 webpack 配置时默认开启），关闭 productionBrowserSourceMaps 和 experimental.serverSourceMaps，并用 next build --experimental-debug-memory-usage 测量。用 typescript.ignoreBuildErrors 跳过类型检查能省内存，但会放过类型错误，所以只在另一个 CI 作业做类型检查时才这样做。

### Skipbox 会在作业之间保留 .next/cache 吗？

会。你的专属机器在作业之间保留检出目录，其中的 .next/cache 也原地保留，不管 Next.js 把它放在哪里（monorepo 里是 apps/web/.next/cache），所以下一次 next build 不需要缓存步骤，直接从上一次的缓存开始。.next 里的其他内容和检出目录中其他未跟踪的文件，在每个作业后都会被清理。npm 或 pnpm 的缓存、setup-node 安装的 Node 版本以及 Docker 的层也留在磁盘上。为 .next/cache 写的 actions/cache 步骤可以保留：在新虚拟机上运行的作业（比如来自 fork 的拉取请求）会从它恢复，而在专属机器上，恢复不会覆盖保留下来的缓存。

### 试用要花多少钱？

不花钱。试用为期 7 天 或 3,000 作业分钟，以先到者为准，无需绑卡，使用 4 vCPU 和 16 GB：是私有仓库 ubuntu-latest 8 GB 的 2 倍，与 GitHub 的 4 核大型运行器相同。在那里试试缓存和内存；需要更多的构建，选 L 套餐，把标签改为 skipbox-16x32（32 GB）。

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