GitLab CI/CD构建时JavaScript堆内存不足问题求助

问题根源 #

你用的AWS EC2 t3a.micro实例只有1GB内存，公司自定义的Node.js镜像大概率存在以下问题：要么默认的Node内存配置比官方node:14镜像更保守，要么镜像内置了额外工具/依赖占用了内存，导致npm install时Node堆内存不足。官方node:14镜像可能默认适配了低内存环境，或者用的npm版本内存占用更低，所以无需配置就能正常构建。

排查与解决步骤 #

1. 先确认NODE_OPTIONS是否真的生效 #

别盲目改参数，先在CI脚本里加两行验证配置：

echo $NODE_OPTIONS
node -e "console.log(v8.getHeapStatistics())"

如果输出里看不到--max-old-space-size，说明环境变量没设对。GitLab CI里正确设置方式：

• 全局配置（.gitlab-ci.yml）：

  variables:
    NODE_OPTIONS: "--max-old-space-size=512" # 注意：实例只有1GB内存，别设8192，物理内存不够根本用不上
  

• 临时在命令前设置：

  NODE_OPTIONS="--max-old-space-size=512" npm install
  

2. 检查镜像的Node/npm版本 #

公司镜像可能用了高版本npm（比如npm 7+），这类版本内存占用比npm 6高很多。在CI里执行：

node -v
npm -v

如果npm版本是7或以上，试试降级到npm 6：

npm install -g npm@6

或者加--legacy-peer-deps参数减少依赖解析的内存消耗：

NODE_OPTIONS="--max-old-space-size=512" npm install --legacy-peer-deps

3. 给运行器加虚拟内存（swap） #

t3a.micro的1GB内存确实紧张，给EC2实例开swap分区能缓解内存压力：
在运行器所在的EC2上执行以下命令：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

这样系统会在内存不足时用swap，虽然构建速度变慢，但不会再出现内存溢出。

4. 排查公司镜像的差异 #

对比官方node:14镜像，检查公司镜像有没有以下改动：

• 自定义了Node启动参数，覆盖了NODE_OPTIONS
• 安装了全局依赖，占用内存
• 修改了npm默认配置（比如并发数、缓存路径）
  可以在CI里跑npm config list，和官方镜像的输出对比，找可能导致内存飙升的配置。

5. 验证运行器是否正常 #

临时把CI的镜像换成官方node:14：

build_job:
  image: node:14
  script:
    - npm install

如果能正常构建，说明问题出在公司自定义镜像上，找镜像维护者调整配置就行；如果还是报错，那就是运行器的内存问题，考虑升级实例规格（比如换成t3a.small，2GB内存）。

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