Node.js 构建报 JavaScript heap out of memory 怎么办？内存诊断与安全恢复

先不要把内存参数直接改到服务器总内存：运行 npm run build、npm run generate 或框架构建命令时出现 FATAL ERROR: Reached heap limit、Ineffective mark-compacts near heap limit、Allocation failed - JavaScript heap out of memory，说明 Node.js 进程触及了 V8 JavaScript 堆限制；如果终端只显示 Killed 或退出码 137，更可能是 Linux 内核或容器把整个进程杀掉。先从 SSH、宝塔终端或 CI 日志保存完整错误，再核对主机可用内存、Swap、容器限制和 Node.js 版本。

只读检查通常不收费，也不会改站点数据。提高 --max-old-space-size 不会删除数据库或上传文件，但会让构建进程可以占用更多内存，可能挤压 MySQL、Redis、PHP-FPM 和线上网站；生成堆快照还会额外消耗内存和磁盘。普通小型站点的默认选择是先停止并发构建、确认实际可用内存，在维护窗口以保守上限单独重跑一次；若服务器余量不足，改在独立构建机完成，再只部署构建产物。

先区分 V8 堆耗尽、系统 OOM 和容器限制

这三种故障的处理方向不同。V8 堆耗尽会在 Node.js 日志里出现 heap limit 和垃圾回收记录；系统 OOM 常在内核日志留下 killed process；容器达到限制时，宿主机仍可能有空闲内存，但容器的 memory.events 或运行状态会显示 OOM。不要看到“内存”两个字就同时加 Swap、扩大容器和提高 Node 堆。

现场证据	更可能的原因	下一步
日志有 Reached heap limit	V8 老生代达到当前限制	核对堆上限和可用内存，再做一次受控重跑
只有 Killed 或退出码 137	Linux OOM、容器限制或人工终止	查看内核和 cgroup 事件，不先提高 Node 参数
构建越跑越慢且 GC 很频繁	接近堆上限，或插件持续保留对象	保存版本、构建阶段和诊断报告，定位高占用步骤
本地能构建，服务器失败	服务器资源更小、版本不同或并发服务更多	对比 Node、锁文件、环境变量、限制与可用内存

第一步：从真实构建账号保存只读现场

进入实际项目目录，并使用宝塔计划任务、CI Runner 或部署脚本真正采用的账号执行。以下命令只读取版本、内存和限制；日志可能包含路径、仓库名和环境变量名称，对外分享前应脱敏。

whoami
pwd
node --version
npm --version
node -p "require('v8').getHeapStatistics().heap_size_limit / 1024 / 1024"
free -h
swapon --show
ulimit -a
cat /sys/fs/cgroup/memory.max 2>/dev/null
cat /sys/fs/cgroup/memory.events 2>/dev/null
journalctl -k --since "30 minutes ago" --no-pager | grep -Ei 'out of memory|oom|killed process'

heap_size_limit 是当前进程可用的 V8 堆上限，不等于 Node 进程的全部常驻内存。Node.js 还会使用原生内存、代码区、Buffer 和线程资源，操作系统与其他服务也要保留余量。如果内核日志出现当前构建进程被杀，应先处理整机或容器容量；这与Linux OOM Killer 排查属于同一层证据。

第二步：确认是不是并发和环境差异

在生产服务器构建前，先看有没有另一轮构建、压缩、备份或依赖安装同时运行。宝塔面板可从“计划任务”和“终端”核对运行账号；CI 需要查看 Runner 并发数。不要直接停止名称相似的进程，先确认 PID、启动命令和负责人。

ps -eo pid,user,etimes,rss,cmd --sort=-rss | head -n 25
pgrep -a -f 'node|npm|pnpm|yarn'
git status --short
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock

最后一条只比较尚未提交的依赖清单与锁文件变化，不应在生产目录随意删除 node_modules 或重写锁文件。若本地与服务器的 Node 主版本、包管理器、锁文件或环境变量不同，先还原可复现环境。升级依赖后才开始耗尽内存时，应把升级提交和旧锁文件作为回退点，而不是永久依靠更大的堆掩盖插件回归。

第三步：在有余量时临时提高堆上限

Node.js 官方提供 --max-old-space-size，单位是 MiB。下面的 2048 只是演示，不是通用推荐值；必须小于可供构建使用的实际内存，并为系统、数据库、Web 服务和 Node 原生内存留出空间。2 GiB 主机不应照抄 2 GiB 堆上限。

NODE_OPTIONS="--max-old-space-size=2048" npm run build

命令只影响本次子进程及其 Node.js 工具。如果维护脚本必须长期使用，可在部署任务的受控环境中设置 NODE_OPTIONS，不要写进公开仓库，也不要把同一个高上限施加给所有常驻 Node 服务。重跑时用 /usr/bin/time -v 记录峰值常驻内存和退出状态，确认问题是否只是默认堆上限。

/usr/bin/time -v env NODE_OPTIONS="--max-old-space-size=2048" npm run build

若构建成功但整机开始 Swap 抖动、网站超时或数据库被 OOM，说明这个上限不可接受。应立即停止继续扩量，恢复原任务配置，并考虑在 CI 或独立构建机生成产物。云服务器升配、临时构建机、CI 用量和构建产物传输可能产生费用，提交前应在对应平台账单页核对。

需要诊断报告时怎么做

Node.js 可以在致命错误时生成诊断报告。报告可能包含命令行、路径、进程和网络信息，只能写入空间充足且权限受控的目录；不要直接把完整报告上传到公开工单。下面的目录必须替换为实际私有诊断目录，并先检查剩余磁盘。

mkdir -p ./private-node-reports
chmod 700 ./private-node-reports

NODE_OPTIONS="--report-on-fatalerror --report-directory=./private-node-reports --report-exclude-env" \
  npm run build

ls -lh ./private-node-reports

先用 node --help 确认当前版本支持这些参数；较旧版本没有 --report-exclude-env 时，不要照抄整条命令，应改在隔离环境生成并手工脱敏。诊断报告适合确认 Node 版本、堆统计、资源限制和故障位置。堆快照比诊断报告更敏感，也更吃内存，可能含业务字符串和构建输入；生产小内存服务器不应把 --heapsnapshot-near-heap-limit 当作第一步。需要分析泄漏时，优先在可复现的隔离环境生成和保管快照。

提高上限仍失败时按什么顺序查

1. 构建输入：检查是否把上传目录、备份、日志或超大 JSON 意外纳入扫描、压缩或静态生成。
2. 插件和依赖：按最近变更缩小范围，核对图片处理、Source Map、类型检查、压缩和静态路由生成阶段。
3. 并发：降低工作线程、页面生成或压缩并发，但只使用当前框架与插件文档支持的参数。
4. Node 版本：使用项目声明且仍受支持的版本重现；不要在故障现场同时升级 Node 和全部依赖。
5. 构建位置：若线上服务器没有安全余量，转到资源隔离的 CI，再部署带校验值的产物。

如果磁盘同时不足，应先按Linux 磁盘满排查清理可确认的临时文件；不要删除正在服务的发布目录或数据库文件。若是 Docker 构建，还要分别核对容器内存限制和构建缓存，不能只看宿主机的 free。

修复后如何验收与回退

验收不能只看命令退出码。先确认构建返回 0，目标目录完整且关键文件时间和校验值符合本次版本；再用预览或临时站点检查首页、深层路由、静态资源和 API 地址。正式切换后观察网站错误、数据库、Swap、系统 OOM 和构建账号权限。部署流程可结合Docker Compose 生产部署保留版本化产物和回退入口。

test -d dist && find dist -maxdepth 2 -type f | head
echo "$?"
free -h
journalctl -k --since "15 minutes ago" --no-pager | grep -Ei 'out of memory|oom|killed process'

目标目录可能叫 dist、build 或 .output，必须按项目实际配置替换。若新依赖、Node 版本或构建参数导致异常，恢复旧锁文件、旧运行时和上一份已验收产物；临时设置的 NODE_OPTIONS 同时撤销。不要在新产物未通过深层路由与业务读写检查前删除上一稳定版本。

官方与上游依据

• Node.js：--max-old-space-size 与内存参数
• Node.js：NODE_OPTIONS 的适用方式与限制
• Node.js：致命错误诊断报告
• Node.js：process.memoryUsage 内存字段