Jenkins 构建 Node 项目内存溢出(JavaScript heap out of memory)解决方案

avatar 2025年8月8日18:27:12 评论 168 次浏览

1. 问题描述

在 Jenkins CI/CD 构建前端项目(Vue / Vite / Webpack 等)时,执行:

 pnpm run build

报错:

 11:31:05  <--- JS stacktrace --->
 11:31:05  
 11:31:05  FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
 11:31:05   1: 0xb85bc0 node::Abort() [node]
 11:31:05   2: 0xa94834  [node]

即 Node.js 在运行时超出了默认 V8 引擎的内存限制(~2GB)。

常见场景:

  • 前端项目依赖多、打包体积大

  • 构建命令中存在多个同时运行的高内存任务(如 vue-tsc + vite build

  • Jenkins / pnpm 子进程没有正确继承 NODE_OPTIONS


2. 原因分析

  • 默认内存限制不足:Node.js 默认最大堆内存约 2GB,在大型构建时不够用。

  • NODE_OPTIONS 未生效:在 Jenkins + pnpm 环境中,NODE_OPTIONS 环境变量可能在子进程中丢失。

  • 多个构建任务并行执行:如 vue-tscvite build 同时运行会造成内存峰值过高。

  • 错误调用 Node 执行 shell 脚本:直接用 node ./node_modules/.bin/xxx 会报语法错误,因为这些文件是 shell 脚本而非纯 JS。


3. 解决方案

3.1 使用 pnpm exec node 加内存参数

package.json 中,将构建命令改为:

 "scripts": {
   "build": "pnpm exec node --max-old-space-size=8192 vue-tsc --noEmit && pnpm exec node --max-old-space-size=8192 vite build"
 }

说明:

  • pnpm exec 会在本地依赖中查找可执行文件(vue-tscvite),并自动用正确的 Node 执行。

  • --max-old-space-size=8192 将 Node 堆内存扩容至 8GB,可根据机器内存调整。

  • 使用 && 串行执行,避免并行任务占用峰值过高的内存。


3.2 其他可选方法(可视情况结合使用)
方法 1:设置环境变量(可能在 Jenkins 中不稳定)
 export NODE_OPTIONS="--max-old-space-size=8192"
 pnpm run build
方法 2:直接调用 JS 入口文件
 node --max-old-space-size=8192 node_modules/vue-tsc/bin/vue-tsc.js --noEmit
 node --max-old-space-size=8192 node_modules/vite/bin/vite.js build

方法 3:升级 Node / 构建工具

  • Node.js ≥ 18 在内存管理上更优化

  • 升级 Vite / Webpack / vue-tsc,避免老版本插件内存泄漏


4. 最终推荐方案

package.json 中固定如下脚本:

 "scripts": {
   "build": "pnpm exec node --max-old-space-size=8192 vue-tsc --noEmit && pnpm exec node --max-old-space-size=8192 vite build",
   "build-only": "pnpm exec node --max-old-space-size=8192 vite build"
 }

优点:

  • 直接在脚本里写死内存参数,避免 Jenkins / pnpm 环境变量传递失败

  • 串行执行降低内存峰值

  • 可在本地、测试、生产构建中通用

avatar

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: