Next.js运行npm run build报Call retries were exceeded错误如何解决

问题现象 #

本地运行npm run build构建Next.js项目时触发报错，相同项目代码在其他设备可正常构建，错误堆栈如下：

Error: Call retries were exceeded
at ChildProcessWorker.initialize (E:\Food-ordering\foor-ordering-app\node_modules\next\dist\compiled\jest-worker\index.js:1:12037)
at ChildProcessWorker._onExit (E:\Food-ordering\foor-ordering-app\node_modules\next\dist\compiled\jest-worker\index.js:1:12975)
at ChildProcess.emit (node:events:526:28)
at ChildProcess.emit (node:domain:475:12)
at Process.ChildProcess._handle.onexit (node:internal/child_process:291:12) {
type: 'WorkerError'
}

错误原因 #

该错误来自Next.js构建时使用的jest-worker多进程编译模块，本质是构建子进程异常退出、重试次数耗尽导致的。同代码跨设备表现不一致，可直接排除业务代码错误，根因均为本地环境问题，常见触发场景：

• 本地可用内存不足，构建子进程被系统强制回收。通常是因为构建时同时运行了虚拟机、多开大型软件、浏览器打开大量标签页占用了绝大多数内存
• Windows环境下Node.js默认内存上限较低，项目页面、依赖较多时容易触发内存溢出
• 本地Node.js版本和项目适配版本不匹配，存在兼容性问题
• 本地node_modules依赖安装过程中出现网络波动、文件损坏

修复方案 #

按操作成本从低到高依次尝试：

• 关闭所有无关的高内存占用程序，释放内存后重新执行npm run build
• 调高Node.js运行内存上限，修改package.json内的build脚本：
  类Unix系统（Mac/Linux）直接修改为：

  "build": "NODE_OPTIONS=--max-old-space-size=4096 next build"
  

  Windows系统如果执行上述命令报错，先执行npm i cross-env -D安装跨平台环境变量工具，再把脚本修改为：

  "build": "cross-env NODE_OPTIONS=--max-old-space-size=4096 next build"
  

  上述配置将Node.js可用内存上限调整为4GB，可根据自身设备内存大小调整数值。
• 对齐Node.js版本：确认能正常构建设备的Node.js大版本，本地切换到对应LTS版本（优先选择18.x、20.x长期支持版），避免使用奇数版本的非稳定Node发行版。
• 重装依赖：删除本地node_modules文件夹、package-lock.json文件，执行npm cache clean --force清空npm缓存后，重新执行npm install安装依赖，再尝试构建。
• 临时关闭构建多进程：如果上述操作都无效，可在next.config.js中添加如下配置，限制构建时只用单核心运行，规避子进程被杀问题：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    experimental: {
      cpus: 1
    }
  }
  module.exports = nextConfig
  

  注意：该配置会明显降低构建速度，仅作为兜底方案使用

内容的提问来源于stack exchange，提问作者haya1111 ibra2