2026 프론트엔드 SSR 빌드 함정:
원격 Mac에서 Next.js·Nuxt — Node 메모리·빌드 동시성 대조표
대상: 원격 Mac에서 Next.js 또는 Nuxt로 SSR·하이브리드 앱을 빌드하는 프론트엔드·풀스택 엔지니어와 릴리즈/플랫폼 담당자입니다. 핵심 키워드: 원격 Mac, Next.js, Nuxt, Node 메모리, 빌드 동시성. 본문은 CI/CD 파이프라인에 그대로 붙여 쓸 수 있는 환경 변수·동시성 상한·캐시 경로를 표와 체크리스트로 정리했습니다. 모노레포·원격 캐시 정합은 pnpm·Turborepo 체크리스트, Node 버전 격리는 다중 프로젝트 Node 분리 가이드와 함께 보시면 좋습니다.
01 메모리 상한과 OOM이 잘 나는 임계 구간
원격 Mac 빌드 에이전트에서 가장 흔한 실패는 기본 힙 한도를 그대로 둔 채 대규모 타입체크·번들·정적 생성이 겹치는 경우입니다. 스왑에만 의존하면 성공은 해도 시간이 배로 늘고, CI 타임아웃으로 실패로 보이기도 합니다.
빌드 스크립트 앞단에서 힙 상한을 명시하세요. 예: export NODE_OPTIONS=--max-old-space-size=6144 (단위 MB). 중규모 앱은 4096~6144MB, 타입·그래프가 큰 모노레포는 8192MB 부근부터 시도하는 팀이 많습니다. next build·nuxt build·nuxt generate 모두 동일한 Node 프로세스를 쓰므로 한 번만 선언하면 됩니다.
| 항목 | Next.js | Nuxt 3 |
|---|---|---|
| 힙 적용 | NODE_OPTIONS를 빌드 전 export |
Vite·Nitro 단계 동일 |
| OOM 흔한 지점 | 다수 페이지·SWC·큰 소스맵 | 에일리어스 많은 Vite 그래프·Nitro 프리번들 |
| 완화 | 단계 분리(린트/타입/빌드 잡 분할) | nitro preset·빌드 분석으로 엔트리 축소 |
02 동시 워커·빌드 병렬과 CPU(vCPU) 관계 표
워커·잡 수를 늘리면 CPU뿐 아니라 RSS 피크가 동시에 여러 개 올라갑니다. 같은 머신에서 행렬 빌드 두 개를 겹치면 “코어는 남는데 메모리만 터지는” 패턴이 자주 납니다.
Turbo·pnpm을 쓰는 경우 예시: turbo run build --concurrency=2, pnpm -r build --workspace-concurrency=2. libuv 스레드 풀은 UV_THREADPOOL_SIZE=8처럼 단계적으로 올리고, 디스크 I/O 병목이면 오히려 줄이는 편이 낫습니다.
| vCPU(노드 기준) | 권장 동시 SSR 빌드 수 | 비고 |
|---|---|---|
| 4 | 1 | 메모리 경합·스왑 위험 최고 |
| 8 | 1~2 | 2개면 힙을 낮추거나 한쪽은 큐 대기 |
| 12+ | 2 | SSD 여유·thermal·다중 테넌트 I/O 확인 |
03 캐시 디렉터리와 정리 전략
Next.js는 .next/cache, node_modules/.cache 등이 쌓이고, Nuxt 3는 .nuxt·.output·node_modules/.vite가 대표적입니다. 메이저 업데이트 직후 이상 증상이면 rm -rf .next .nuxt .output node_modules && pnpm install 같은 풀 클린이 가장 빠른 분기입니다.
CI 캐시 키에는 lockfile 해시·Node 메이저·OS·아키텍처(arm64/x64)를 넣어 원격 Mac과 로컬 산출물이 섞이지 않게 하세요. 주간 풀 클린 한 번이 디스크 단편화·고아 캐시를 줄입니다. Vite/Webpack 공통 최적화는 원격 Mac 빌드 캐시 최적화 글을 참고하세요.
- CI 5단계:
df -h·여유 메모리 로그 남기기 - 중복 방지:
NODE_OPTIONS는 잡 레벨에서 한 번만 설정 - 슬롯: 행렬 대신 전역 세마포어·큐로 동시 빌드 제한
- 재현: 실패 시 캐시 끈 일회 재실행으로 캐시 오염 판별
04 원격 노드 안정성 FAQ
요약하면 세 가지입니다. (1) 힙 대역을 4096~8192MB 중에서 앱에 맞게 고정 (2) 동시 빌드는 vCPU의 절반을 넘기지 말고 큐로 흡수 (3) 캐시 키를 고정하면 재빌드 시간을 30~50%까지 줄일 수 있는 경우가 많습니다.
Q. 특정 시간대에만 실패합니다
호스트 부하·스왑·네트워크 스토리지 지연이 겹친 경우가 많습니다. 동시성을 낮추고 NODE_OPTIONS·캐시 경로를 잡마다 동일하게 유지하세요.
Q. Next와 Nuxt 캐시를 섞어 지워도 되나요?
같은 리포에 둘 다 있으면 각각의 산출물 경로를 표대로 삭제하세요. 공유 node_modules는 한 번에 지우는 것이 안전합니다.
export NODE_OPTIONS=--max-old-space-size=6144 후 pnpm exec next build 또는 pnpm exec nuxt build. GitHub Actions·GitLab CI·Jenkins 모두 동일하게, 빌드 스텝의 env 블록에 선언하면 스크립트 중복을 피할 수 있습니다.
| 단계 | 할 일 | 통과 기준 |
|---|---|---|
| 1 | 잡 시작 시 NODE_OPTIONS·동시성 변수 출력 | 로그에 기대 값과 일치 |
| 2 | 동시 빌드 슬롯 ≤ 표 권장 | RSS 피크가 물리 RAM 이내 |
| 3 | 캐시 restore 후 해시 검증 | lockfile·Node 메이저 불일치 시 미스 |
| 4 | 실패 시 캐시 없이 1회 재시도 | 재현 여부로 원인 분리 |
SSR 빌드용 원격 Mac 노드 선택하기
MacWww에서는 로그인 없이 홈에서 요금·노드 구성을 확인할 수 있고, 전용 요금 페이지에서 플랜을 바로 비교할 수 있습니다. SSH·VNC 접속 절차는 도움말을 참고하세요. Next.js·Nuxt SSR 빌드에 힙·동시성 여유를 두고 싶은 팀은 Apple Silicon 원격 Mac부터 검토해 보세요.