---
title: "记一次\"本地秒过、CI 必挂\"的前端构建 OOM 复盘"
date: 2026-10-11
description: "本地 pnpm build 秒过、CI 一到转译阶段就 exit 134：用 git diff 做控制变量后，真凶是解压超 60MB 的汉字拼音字典，Rollup 为它构建 AST 时顶破了容器里约 2GB 的 V8 堆，顺带揪出被通配规则打进构建图的 copy.vue 备份。"
canonical_url: "https://yijinlee.com/articles/article-73"
tags:
  - Vite
  - Rollup
  - Node.js
  - V8
  - pnpm
  - Jenkins
  - "AI Coding"
topic: "AI 外骨骼"
---

METRICS: 2080 MB|JavaScript 堆上限 · 134|进程退出码 · >60 MB|拼音字典解压体积 · 2.8 G|CI 容器内存上限

本地 `pnpm build` 顺顺当当，代码一推到流水线，Jenkins 就在转译阶段当场暴毙——熟悉的 JavaScript heap out of memory，堆内存死死卡在 2080MB，进程 exit 134。

最搞人心态的是：同一台 Runner 节点，跑 master 分支稳如泰山，新分支必挂。显然，问题出在分支的增量代码里。但排查过程并没有想象中顺利，中途踩了两个极其逼真的"假现场"。

### 两次打脸的推测

下面两个推测都曾让我以为已经破案，结果先后被证伪。先看推测，再展开证据。

#### 第一个烟雾弹：依赖源差异

在本地排查时，`pnpm install` 报了某个工具包 404，查证发现该包确实在官方源下架了，下意识以为是依赖损坏导致构建异常。

EVIDENCE: 翻看 CI 日志发现依赖安装全部成功——CI 走的是内部镜像源，包完好无损。本地的 404 纯属网络环境差异带来的干扰，与 OOM 毫无关系。

#### 第二个假象：顺手留下的备份文件

排查代码时，在一处不知何时提交的 `index copy.vue` 里发现了一行离谱的导入，疑似把某个 Node CLI 模块引进了前端。当时以为破案了：打包工具把这玩意儿打进 Bundle 能不撑爆？

EVIDENCE: 然而去 master 一查，相同的文件早就存在且构建正常；在分支里把那行代码注释掉再推一次，内存溢出分毫不差地再次复现。推测再次被证伪。

### 老老实实做 Diff，真凶浮出水面

不再凭直觉瞎猜，老老实实用 `git diff master...branch` 审查依赖变动。增量里赫然躺着一个汉字拼音转换库。一查元数据，它的解压体积居然超过 60MB——里面塞了一整部完整的汉字静态拼音字典。

Vite 在构建转译（Transform）阶段，Rollup 需要在内存中为模块构建 AST（抽象语法树）。当遇到包含数万行巨型对象字面量的字典文件时，AST 节点数量瞬间呈指数级爆炸，把内存直接顶破。

顺带发现，约定式路由插件因为通配规则，把 `copy.vue` 这类备份文件也默默打包了进来，无形中又给内存加了码。

### 那为什么本地能过？

Node V8 默认堆上限会参考宿主环境的可用内存。本地机器动辄 16G、32G，V8 自动分了 4G 以上的堆；而 CI 容器被 cgroup 限制在 2.8G 左右，V8 算出来的堆上限只有约 2GB。

60MB 的源码字典，在本地咬咬牙过去了，但在容器里成了压垮骆驼的最后一根稻草。同一个峰值、两套天花板，结果就此分岔。

### 留给团队的避坑备忘

1. **别凭直觉猜，相信 `git diff`**：面对环境特异性构建失败，先用主干分支做控制变量，增量依赖和代码差异才是最快定位问题的突破口。
2. **严防"服务端级"大包进前端**：像庞大字面量字典这类重型数据，原则上应由后端处理后下发接口。加依赖前顺手看一眼体积，超过 1MB 必须打个问号。
3. **给 CI 构建留点容错空间**：构建命令显式加上 `NODE_OPTIONS=--max-old-space-size=4096`，别让脆弱的默认内存天花板轻易卡死交付流水线。
4. **管住手，别把 `xxx copy.vue` 留在代码库**：配置 Git Hook 拦截临时文件提交。构建插件比你想象的更"勤奋"，它们往往不管这是不是备份，都会一股脑塞进构建图里。

## 参考文章：相关链接

- [Node.js CLI · --max-old-space-size](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-mib)（官方文档）— 显式抬升 V8 老生代堆上限，是给 CI 构建留容错空间的官方开关。
- [Vite · Troubleshooting](https://vite.dev/guide/troubleshooting)（官方文档）— 官方排障指南，覆盖构建期内存与产物体积异常的定位入口。
- [Rollup · 官方文档](https://rollupjs.org/)（官方文档）— 模块图与 AST 转换的实现说明，帮助理解字典文件为何会放大内存占用。
- [首页 LCP 优化复盘：HTML 减到 50 KB，LCP 没有变快](https://yijinlee.com/articles/article-50)（站内深度）— 同样把"体积与峰值开销"当作交付红线，用证据链而不是直觉来定位根因。

