JavaScript heap out of memory는 코드 한 줄이 틀린 게 아니라 노드 힙 한도를 빌드가 다 써서 프로세스가 죽은 줄입니다. 맥 여유 램과 노드 힙은 다른 칸이고, 빌드 스크립트 NODE_OPTIONS, 버셀 환경 변수, 소스맵과 큰 JSON을 먼저 봅니다. Next.js, 깃허브 액션, 한국 1인 개발자 기준. 2026년 9월 Node.js CLI·Next.js 배포 문서.
JavaScript heap out of memory는 코드 한 줄이 틀린 게 아니라, 노드가 쓸 수 있는 힙을 빌드가 다 써서 프로세스가 죽은 줄입니다. 넥스트 next build가 중간까지 가다가 빨간 줄로 끝나면, 의존성부터 지울 게 아니라 힙 한도와 빌드 캐시부터 보세요.
한국에서 1인으로 넥스트를 여러 개 돌리면, 맥 메모리 압박 경고와 노드 힙 에러가 같은 날 겹치기도 합니다. 창은 살아 있는데 빌드만 죽는 패턴이죠.
패키지를 지워 다시 깔기 전에 max-old-space-size와 캐시 폴더를 먼저 맞춥니다. 근거는 Node.js CLI와 Next.js 배포 문서에 있습니다.
노드 힙 한도를 넘긴 빌드입니다. 메시지에 FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory가 있으면, 운영체제 전체가 다운된 게 아니라 그 노드 프로세스가 자기 힙을 다 쓴 겁니다.
기본 힙은 머신 램과 다릅니다. 64비트 노드는 예전에 약 2GB 근처에서 막히는 경우가 많았고, 최근 버전도 빌드처럼 큰 작업은 기본값만으로 부족한 프로젝트가 있습니다. 맥 활동 모니터에 여유 램이 보여도, 그 노드 프로세스의 힙 한도는 따로입니다.
설치 에러와 자리도 다릅니다. ERESOLVE는 트리를 못 만들어 설치가 멈추고, 힙 부족은 설치 이후 빌드 과정에서 납니다. 설치 쪽은 npm ERESOLVE를 보세요. 여기서는 next build나 웹팩이 죽는 줄만 봅니다.
먼저 기억할 것 | 활동 모니터의 여유 램과 노드 힙은 다른 칸입니다. 램이 남아 있어도 힙 한도만 넘으면 빌드는 죽습니다.
두 경고를 한 줄로 취급하면 원인을 놓칩니다. 맥이 메모리 압박을 띄우면 스왑이 늘고 전체가 느려집니다. 노드 힙 에러는 그 프로세스만 즉시 종료됩니다.
| 칸 | 보이는 것 | 먼저 할 일 |
|---|---|---|
| 노드 힙 | heap out of memory, 프로세스 즉시 종료 | NODE_OPTIONS로 힙 한도 올리기 |
| 맥 압박 | 팬, 스왑, 전체 슬로다운 | 다른 앱 종료, 빌드 하나만 |
| CI 러너 | 깃허브 액션만 죽음 | 러너 스펙과 캐시, 힙 옵션 |
| 버셀 빌드 | 로컬은 되고 배포 빌드만 죽음 | 프로젝트 NODE_OPTIONS, 캐시 |
| 모듈 해석 | 빌드 전 기동 실패 | Cannot find module 칸 |
버셀 빌드는 로컬 맥보다 한도가 낮을 수 있습니다. 로컬에서 8GB 힙으로 겨우 통과한 빌드가 프리뷰에서 다시 죽으면, 프로젝트 환경 변수에 같은 NODE_OPTIONS를 넣었는지부터 보세요. 모듈을 못 찾아 빌드가 시작도 못 하면 Cannot find module입니다.
빌드를 실행하는 그 노드 프로세스에 넣어야 먹습니다. 셸에만 넣고 npm 스크립트가 새 노드를 띄우면 옵션이 사라질 수 있어요.
Node.js CLI 문서 기준으로 --max-old-space-size는 메가바이트 단위입니다. 4096이면 약 4GB입니다. NODE_OPTIONS=--max-old-space-size=4096을 package.json의 build 스크립트에 붙이면, 로컬과 CI가 같은 한도를 씁니다.
전역 셸에만 크게 올리는 방법은 피하세요. 카카오 콜백 개발 서버까지 큰 힙을 들고 뜨면, 노트북에서 여러 넥스트를 동시에 열 때 맥 압박이 먼저 옵니다. 빌드 스크립트에만 넣는 편이 안전합니다.
빌드 스크립트에만 힙 한도 넣기# package.json # "build": "NODE_OPTIONS=--max-old-space-size=4096 next build" # 한 번만 시험 NODE_OPTIONS=--max-old-space-size=4096 npx next build # 현재 노드가 옵션을 받았는지 node -e "console.log(process.execArgv, process.env.NODE_OPTIONS)"
힙만 올리는 건 임시입니다. 빌드가 비대해진 이유를 같이 줄여야 다음 배포에서 같은 줄이 안 납니다.
흔히는 소스맵, 큰 정적 데이터, 캐시 꼬임입니다. next.config.js에서 production 소스맵을 켜 두면 빌드 메모리가 눈에 띄게 늘어납니다. data/에 큰 JSON을 그대로 import하면 번들과 빌드 힙이 함께 커집니다. .next가 깨진 채 남아 있으면 지우고 다시 빌드하는 편이 빠릅니다.
이미지 파이프라인도 한몫합니다. 본문 JPG를 빌드 중에 많이 처리하면 힙이 잠깐 치솟습니다. 썸네일 생성은 빌드와 분리된 스크립트로 빼 두는 편이 한국에서 여러 사이트를 혼자 빌드할 때 안전합니다.
포트가 막혀 이전 개발 서버가 살아 있으면 램을 같이 먹습니다. 빌드 전에 개발 서버를 끄고, 필요하면 EADDRINUSE로 포트를 비우세요. 노드 버전이 빌드 머신마다 다르면 도구 버전 고정도 함께 맞춥니다.
힙을 무한히 올리지 말 것 | 8192, 16384로 계속 키우면 버셀 빌드 한도나 맥 스왑만 먼저 터집니다. 4096에서 통과하는지 보고, 안 되면 소스맵과 큰 JSON import를 줄이세요.
로컬 맥은 통과하고 CI만 죽으면 러너 램과 캐시입니다. 깃허브 호스티드 러너는 로컬 16GB 맥보다 빠듯합니다. 워크플로에 NODE_OPTIONS를 넣고, actions/setup-node 캐시와 Next.js 캐시가 깨지지 않았는지도 보세요.
버셀은 프로젝트 Settings의 Environment Variables에 NODE_OPTIONS를 넣습니다. 로컬 .env만 바꾸고 프리뷰에 안 넣으면 배포 빌드만 다시 죽습니다. 토스 웹훅이나 카카오 콜백이 있는 앱도 빌드 단계에선 그 API를 안 부르니, 런타임 에러와 빌드 힙 에러를 로그에서 섞지 마세요.
| 환경 | 넣을 곳 | 주의 |
|---|---|---|
| 로컬 | package.json build 스크립트 | dev 스크립트엔 넣지 않기 |
| 깃허브 액션 | job env NODE_OPTIONS | 러너 램 한도 안쪽 |
| 버셀 | 프로젝트 Environment Variables | Production과 Preview 모두 |
공식 문서 다섯 곳을 기준으로 적었습니다.
내부 연계: npm ERESOLVE, 모듈을 찾을 수 없음, 포트 점유, 노드 버전 고정
인용한 동작은 2026년 9월 공개 문서 기준입니다.
운영체제 램과 노드 힙 한도는 다릅니다. 여유 램이 보여도 그 프로세스 힙이 가득 차면 죽습니다. NODE_OPTIONS로 빌드 프로세스 한도만 올리세요.
먼저 4096(약 4GB)으로 빌드가 끝나는지 보세요. 안 되면 소스맵과 큰 JSON import를 줄인 뒤 다시 시도합니다. 숫자를 계속 키우는 것만으로는 버셀 빌드 한도에 다시 막힙니다.
로컬 셸에만 NODE_OPTIONS가 있고 버셀 프로젝트 환경 변수에는 없는 경우가 많습니다. Production과 Preview 모두에 같은 값을 넣고, .next 캐시가 깨진 빌드인지도 보세요.
보통은 아닙니다. 개발 서버까지 큰 힙을 주면 카카오 콜백용 넥스트를 여러 개 띄울 때 맥 압박이 먼저 옵니다. build 스크립트에만 넣는 편이 안전합니다.
의존성 트리 문제와 힙 부족은 칸이 다릅니다. 지워 깔기는 ERESOLVE나 깨진 설치에 쓰고, 힙 에러는 한도와 캐시, 소스맵을 먼저 보세요. 설치 로그와 빌드 로그를 섞지 마세요.
캐시 꼬임이 아니면 힙 한도나 큰 입력 데이터입니다. 빌드 스크립트 옵션을 확인한 뒤, 정적 JSON을 런타임 읽기로 바꾸거나 소스맵을 끄고 다시 빌드하세요.
