一、报错说明

plaintext

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

报错含义

Node.js V8 堆内存不足，打包 / 编译时内存占用超过默认上限，进程直接崩溃。

常见场景：大项目、多页面、大量静态资源、TS 类型复杂、低配置服务器打包。

二、快速临时修复（立即生效）

1. 命令行临时扩容内存（Linux/macOS）

bash

运行

# 单次构建，分配4GB内存
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

# 开发启动
export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

Windows CMD：

cmd

set NODE_OPTIONS=--max-old-space-size=4096
npm run build

Windows PowerShell：

powershell

$env:NODE_OPTIONS="--max-old-space-size=4096"
npm run build

参数说明：

--max-old-space-size=4096 = 4G，大型项目可改为 6144（6G）、8192（8G）

三、永久全局配置（推荐，不用每次输命令）

方案 1：修改 package.json scripts

json

{
  "scripts": {
    "dev": "NODE_OPTIONS=--max-old-space-size=6144 vite",
    "build": "NODE_OPTIONS=--max-old-space-size=6144 vite build"
  }
}

Windows 跨平台兼容写法（使用 cross-env）：

bash

运行

npm i cross-env -D

json

{
  "scripts": {
    "build": "cross-env NODE_OPTIONS=--max-old-space-size=6144 vite build"
  }
}

方案 2：系统环境变量永久生效

Linux/macOS

bash

运行

# 写入 ~/.bashrc 或 ~/.zshrc
echo 'export NODE_OPTIONS="--max-old-space-size=6144"' >> ~/.zshrc
source ~/.zshrc

四、项目层面优化（治本，减少内存占用）

1. Vite 打包配置优化

1. 开启分包、压缩、关闭无用预构建

ts

// vite.config.ts
export default defineConfig({
  build: {
    // 拆分大依赖
    rollupOptions: {
      output: {
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          vendor: ['axios', 'element-plus']
        }
      },
      // 关闭体积可视化插件（占用大量内存）
      reportCompressedSize: false,
      chunkSizeWarningLimit: 1500
    },
    // 增量编译缓存
    cacheDir: './.vite_cache'
  },
  // 按需引入组件，避免全量导入UI库
  optimizeDeps: {
    include: []
  }
})

2. 清理无用资源

• 删除未使用图片、字体、大型静态文件
• UI 库改为按需导入，不要全量引入
• 注释 / 删除未使用页面、组件、路由

3. 依赖清理

bash

运行

rm -rf node_modules .vite_cache package-lock.json
npm install

4. Node 版本升级

低版本 Node 内存回收机制差，升级至 Node 20 LTS，大幅缓解 OOM。

五、CI / 服务器打包专用方案

服务器内存小（1C2G）时，限制并发 + 扩容内存：

bash

运行

export NODE_OPTIONS="--max-old-space-size=3072"
# 单线程打包，关闭并行
npm run build

六、合并进之前博文的追加章节

追加章节：打包崩溃 FATAL ERROR JS heap out of memory 内存溢出解决

现象

构建中途直接进程退出，堆栈日志：

plaintext

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

根本原因

Node 默认堆内存仅 1.4G 左右，大型前端项目 TS、多页面、大静态资源打包时内存耗尽，V8 GC 回收无效直接崩溃。

方案 1：临时扩容内存（快速救急）

Linux/macOS

bash

运行

export NODE_OPTIONS="--max-old-space-size=6144"
npm run build

Windows CMD

cmd

set NODE_OPTIONS=--max-old-space-size=6144
npm run build

方案 2：package.json 永久配置（推荐）

安装跨平台工具：

bash

运行

npm i cross-env -D

修改 scripts：

json

"scripts": {
  "dev": "cross-env NODE_OPTIONS=--max-old-space-size=6144 vite",
  "build": "cross-env NODE_OPTIONS=--max-old-space-size=6144 vite build"
}

方案 3：Vite 配置优化降低内存消耗

1. 分包拆分第三方依赖，减少单次打包体积
2. 关闭体积统计、大型可视化插件
3. UI 库按需引入，杜绝全量导入

ts

build: {
  rollupOptions: {
    output: {
      manualChunks: {
        core: ['vue', 'vue-router', 'pinia'],
        libs: ['axios', 'echarts']
      }
    }
  },
  reportCompressedSize: false
}

方案 4：服务器 CI 打包优化

低配机器限制内存上限，清理缓存后再打包：

bash

运行

rm -rf node_modules .vite_cache
export NODE_OPTIONS="--max-old-space-size=3072"
npm install && npm run build

避坑总结

1. 内存数值单位 MB：4096=4G、6144=6G、8192=8G，根据服务器配置调整；
2. 优先升级 Node 20 LTS，老旧 Node 内存回收效率极低；
3. 不要全量引入 Element Plus / Ant Design Vue 等大型 UI 库；
4. 持续出现 OOM 优先拆分路由分包、清理无用静态资源。