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

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-tsc 与 vite 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-tsc、vite），并自动用正确的 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 环境变量传递失败

• 串行执行降低内存峰值

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