GitHub Actions 中 Next.js 构建慢或内存不足:缓存、内存、运行器规格
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 一开始是空的
根据 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') }}-
源代码每改一次,键就变一次,所以每次运行都保存一个新条目,占用 GitHub 每个仓库 10 GB 的空间。在 Turborepo 中,把 .next/cache 从任务的 outputs 中排除("!.next/cache/**"),就像 Turborepo 的 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 的内存使用指南:
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 上的组织,按分钟计费(大型运行器) |
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 |
切换只需改一行
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。
- 使用 GitHub 登录 Skipbox。
- 安装 Skipbox GitHub 应用,并选择仓库。
- 修改
runs-on并推送。
安全
- 这台机器只属于你的账号。不会运行其他公司的作业。
- 每个作业结束后,运行器的凭据、进程和容器都会被清除,保留的检出目录中的 git 凭据,以及
.next/cache这类构建缓存以外的未跟踪文件也一样。开启“每个作业用新虚拟机”后,每个作业改在一台新机器上运行。 - 没有写入权限的人提交的代码(例如来自复刻的拉取请求)在一台新的虚拟机上运行,它能读取你的缓存,但不能修改。
详情见作业如何隔离。
用 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日