TypeScript编译时遇JavaScript堆内存不足错误，求解释及修复指引

错误日志 #

<--- Last few GCs --->

[1791:0x5533880]    72626 ms: Scavenge (reduce) 2042.8 (2082.2) -> 2042.1 (2082.5) MB, 10.0 / 0.0 ms  (average mu = 0.287, current mu = 0.243) allocation failure 
[1791:0x5533880]    74247 ms: Mark-sweep (reduce) 2043.0 (2082.5) -> 2037.5 (2082.5) MB, 1617.4 / 0.0 ms  (average mu = 0.225, current mu = 0.159) allocation failure scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
 1: 0xb09c10 node::Abort() [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 2: 0xa1c193 node::FatalError(char const*, char const*) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 3: 0xcf8dbe v8::Utils::ReportOOMFailure(v8::internal::Isolate*, char const*, bool) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 4: 0xcf9137 v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, bool) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 5: 0xeb09d5  [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 6: 0xeb14b6  [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 7: 0xebf9de  [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 8: 0xec0420 v8::internal::Heap::CollectGarbage(v8::internal::AllocationSpace, v8::internal::GarbageCollectionReason, v8::GCCallbackFlags) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
 9: 0xec339e v8::internal::Heap::AllocateRawWithRetryOrFailSlowPath(int, v8::internal::AllocationType, v8::internal::AllocationOrigin, v8::internal::AllocationAlignment) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
10: 0xe848da v8::internal::Factory::NewFillerObject(int, bool, v8::internal::AllocationType, v8::internal::AllocationOrigin) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
11: 0x11fd626 v8::internal::Runtime_AllocateInYoungGeneration(int, unsigned long*, v8::internal::Isolate*) [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]
12: 0x15f2099  [/opt/hostedtoolcache/node/16.15.0/x64/bin/node]

环境信息：Node.js: 16.15.0，TypeScript: 4.2.4

错误解释 #

这个错误是Node.js进程的JavaScript堆内存不足导致的。从日志中的垃圾回收（GC）记录可以看到，V8引擎先后尝试了Scavenge和Mark-sweep两种垃圾回收策略，但回收后仍无法腾出足够内存来完成TypeScript编译任务，最终触发致命的内存溢出错误。TypeScript编译大型项目时需要加载并处理大量类型定义、源文件，当项目规模超出Node.js默认堆内存限制时就会出现这类问题。

修复方向 #

• 临时扩容Node.js堆内存：在编译命令前添加堆内存配置，比如NODE_OPTIONS="--max-old-space-size=4096" tsc（4096表示分配4GB内存，可根据项目实际情况调整数值）
• 优化TypeScript编译配置：
  • 启用增量编译：在tsconfig.json中设置"incremental": true，仅重新编译修改过的文件
  • 精准控制编译范围：通过exclude字段排除不需要编译的文件（如node_modules、测试文件），缩小include字段仅包含核心源码
  • 跳过第三方库类型检查：设置"skipLibCheck": true，减少不必要的类型校验开销
• 拆分大型项目：将项目拆分为多个独立子模块，分别编译，避免单次编译加载过多文件
• 升级依赖版本：新版本Node.js（18+）和TypeScript（4.8+）对内存管理、编译性能有优化，能有效降低内存占用

内容的提问来源于stack exchange，提问作者captain-yossarian from Ukraine