React项目在AWS EC2 t2.micro构建时出现JS堆内存不足错误

环境信息 #

• React版本：18.2.0
• Node.js版本：v16.18.0
• Npm版本：8.19.2

问题描述 #

在AWS EC2 t2.micro（Ubuntu系统）上执行npm run build构建React项目时，触发JavaScript堆内存溢出错误，具体报错信息如下：

<--- Last few GCs --->

[1623:0x6338df0]    66411 ms: Scavenge 471.0 (491.0) -> 467.5 (491.2) MB, 2.1 / 0.0 ms  (average mu = 0.211, current mu = 0.097) allocation failure
[1623:0x6338df0]    66444 ms: Scavenge 471.2 (491.2) -> 467.8 (491.5) MB, 2.2 / 0.0 ms  (average mu = 0.211, current mu = 0.097) allocation failure
[1623:0x6338df0]    67665 ms: Mark-sweep 471.4 (491.5) -> 464.1 (491.7) MB, 1191.7 / 0.0 ms  (average mu = 0.269, current mu = 0.324) allocation failure scavenge might not succeed

<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
1: 0xb06730 node::Abort() [/usr/bin/node]
2: 0xa1b6d0  [/usr/bin/node]
3: 0xce1dd0 v8::Utils::ReportOOMFailure(v8::internal::Isolate*, char const*, bool) [/usr/bin/node]
4: 0xce2177 v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, bool) [/usr/bin/node]
5: 0xe997e5  [/usr/bin/node]
6: 0xe9a2c6  [/usr/bin/node]
7: 0xea87ee  [/usr/bin/node]
8: 0xea9230 v8::internal::Heap::CollectGarbage(v8::internal::AllocationSpace, v8::internal::GarbageCollectionReason, v8::GCCallbackFlags) [/usr/bin/node]
9: 0xeac1ae v8::internal::Heap::AllocateRawWithRetryOrFailSlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [/usr/bin/node]
10: 0xe6d6ea v8::internal::Factory::NewFillerObject(int, bool, v8::internal::AllocationType, v8::internal::AllocationOrigin) [/usr/bin/node]
11: 0x11e6456 v8::internal::Runtime_AllocateInYoungGeneration(int, unsigned long*, v8::internal::Isolate*) [/usr/bin/node]
12: 0x15da0d9  [/usr/bin/node]

已尝试操作 #

• 执行export NODE_OPTIONS=--max-old-space-size=2048调整Node内存限制，后续尝试过4GB、8GB、16GB的参数，均未解决问题。

补充信息 #

本地MacOS Monterey系统可正常完成构建，本地环境：

• Node版本：v16.13.1
• Npm版本：8.3.0
• React版本：18.2.0

解决方案 #

1. 解决核心问题：EC2实例内存不足 #

t2.micro仅提供1GB内存，React生产打包过程需要的内存超过了实例的可用资源，这是主要原因。可通过两种方式解决：

临时升级实例规格

将t2.micro临时升级到t2.small（2GB内存），完成构建后再降级回原规格，避免额外长期成本。

添加交换空间（Swap）

给实例添加虚拟内存，步骤如下：

# 创建4GB交换文件
sudo fallocate -l 4G /swapfile
# 设置文件权限
sudo chmod 600 /swapfile
# 初始化交换文件
sudo mkswap /swapfile
# 启用交换空间
sudo swapon /swapfile
# 设置开机自动挂载交换空间
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

完成后重新执行构建命令。

2. 正确设置Node内存参数 #

之前的环境变量设置可能未生效，建议直接在构建命令前追加参数，避免环境变量全局生效的问题：

NODE_OPTIONS=--max-old-space-size=1536 npm run build

（设置为1.5GB是结合t2.micro的1GB物理内存+swap后的合理值，避免过度分配）

3. 排查版本兼容性问题 #

虽然v16分支的Node版本差异较小，但可以尝试将EC2的Node版本降级到本地使用的v16.13.1，排除版本带来的构建差异：

# 安装nvm管理Node版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# 安装指定版本并切换
nvm install 16.13.1
nvm use 16.13.1

4. 优化项目构建过程 #

• 清理npm缓存并重新安装依赖：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

• 检查项目依赖，移除未使用的包，大型库采用按需引入方式；确保package.json中的build命令为标准的react-scripts build。

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