GitHub Actions에서 Next.js 빌드가 느리거나 메모리가 바닥날 때: 캐시, 메모리, 실행기 크기
GitHub Actions의 Next.js 빌드는 한 가지 이유로 느리고, 다른 이유로 메모리가 바닥나요. 느린 건 .next/cache가 다음 실행으로 이어지지 않을 때예요. Next.js는 빌드 사이에 그 캐시를 다시 쓰는데, GitHub 호스팅 작업은 새 VM에서 시작하므로 캐시 단계가 없으면 모든 빌드가 콜드 빌드예요(로그에 No Cache Detected가 나와요). 메모리가 바닥나는 건 프라이빗 리포지토리의 ubuntu-latest가 8 GB이고, 큰 앱의 webpack 컴파일, 타입 검사, 소스 맵이 그것을 넘을 수 있기 때문이에요. 첫 번째는 .next/cache에 actions/cache를 걸어 고쳐요. 두 번째는 먼저 Next.js의 메모리 설정(experimental.webpackMemoryOptimizations, 프로덕션 소스 맵 끄기), 그다음 메모리가 더 많은 머신이에요. 16 GB나 32 GB요.
Skipbox는 빌드에 그 메모리를 정액으로 줘요. runs-on: skipbox-8x16에서 16 GB와 8 vCPU가 월 $79, skipbox-16x32에서 32 GB와 16 vCPU가 $149예요. 내 전용 머신에서는 .next/cache가 다음 빌드까지 남고, 패키지 캐시가 디스크에 남고, actions/cache가 저장한 것은 로컬로 읽히며, 실행 시간은 무제한이에요.
느림: .next/cache가 비어 있는 채로 시작해요
Next.js의 CI 빌드 캐시 가이드에 따르면, Next.js는 빌드 사이에 공유되는 캐시를 .next/cache에 저장하고, 빌드 사이에 그것을 유지하지 않는 CI는 No Cache Detected 오류를 보여 줘요. 가이드의 GitHub Actions 단계는 이래요.
- uses: actions/cache@v4
with:
path: |
~/.npm
${{ github.workspace }}/.next/cache
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
restore-keys: |
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
키는 소스가 바뀔 때마다 바뀌므로, 실행마다 새 항목을 리포지토리당 GitHub의 10 GB 안에 저장해요. Turborepo에서는 Turborepo의 GitHub Actions 가이드처럼 작업의 outputs에서 .next/cache를 빼세요("!.next/cache/**").
메모리 부족: 서로 다른 두 오류
| 로그에 나오는 것 | 바닥난 것 | 할 일 |
|---|---|---|
JavaScript heap out of memory | Node 자체의 힙 한도. 머신에는 아직 메모리가 있었어요 | 올리세요: NODE_OPTIONS=--max-old-space-size=6144, 머신의 메모리보다 낮게 |
Process completed with exit code 137 | 머신의 메모리. Linux가 프로세스를 강제로 끝냈어요 | 메모리를 덜 쓰거나, 더 많은 머신을 쓰세요 |
힙을 머신의 메모리보다 높이면 첫 번째 오류가 두 번째 오류로 바뀌어요.
메모리를 덜 쓰기: Next.js 자체의 설정
Next.js의 메모리 사용 가이드에서:
experimental.webpackMemoryOptimizations: true(v15.0.0 이상)는 컴파일이 조금 길어지는 대신 webpack의 최대 메모리를 낮춰요.- webpack 빌드 워커는 컴파일을 별도의 Node 워커에서 돌려 메모리를 낮춰요. v14.1.0부터 사용자 webpack 설정이 없으면 기본으로 켜져 있고, 설정이 있다면
experimental.webpackBuildWorker: true를 정하세요. - 소스 맵 끄기:
productionBrowserSourceMaps: false와experimental.serverSourceMaps: false. "Generating static pages" 중에 바닥난다면enablePrerenderSourceMaps: false도요. - 측정:
next build --experimental-debug-memory-usage(v14.2.0 이상)는 빌드 내내 힙 사용량을 출력하고, 한도 가까이에서 힙 스냅샷을 찍어요. - 타입 검사:
typescript.ignoreBuildErrors: true는 타입 검사와 그 메모리를 건너뛰고, 타입 오류를 빌드에 들여보내요. 다른 단계가 타입을 검사하지 않는 한 Next.js는 하지 말라고 경고해요.
메모리가 더 많은 머신 쓰기
| 실행기 | CPU와 메모리 | 쓸 수 있는 곳 |
|---|---|---|
GitHub ubuntu-latest, 프라이빗 리포지토리 | CPU 2개, 8 GB | 누구나 |
GitHub ubuntu-latest, 퍼블릭 리포지토리 | CPU 4개, 16 GB | 퍼블릭 리포지토리 |
| GitHub 대형 실행기, 4코어나 8코어 | 16 GB나 32 GB | GitHub Team과 Enterprise Cloud 조직, 분 단위(대형 실행기) |
Skipbox skipbox-8x16 | 8 vCPU, 16 GB | 조직과 개인 계정, 월 $79 |
Skipbox skipbox-16x32 | 16 vCPU, 32 GB | 조직과 개인 계정, 월 $149 |
월 20,000분이면 GitHub 8코어 실행기는 $422, Skipbox M은 $79예요. 16코어라면 $822 대 L의 $149예요. GitHub 쪽 금액은 GitHub Team에 포함된 사용량을 뺀 금액이에요.
Skipbox가 Next.js 빌드에 해 주는 것
요금제마다 작업 사이에도 유지되는 내 계정 전용 머신이 따라와요.
- 빌드에 필요한 메모리를 레이블로: M은 16 GB, L은 32 GB. 힙도 맞춰 정하세요. M이라면
--max-old-space-size=12288처럼요. - 패키지 캐시가 디스크에 남아요:
~/.npm, pnpm 스토어, 도구마다의~/.cache,setup-node가 설치한 Node 버전.npm ci가 레지스트리 대신 그것들을 읽어요. .next/cache가 다음 작업까지 남아요. 머신은 작업 사이에 체크아웃을 남기고, 그 안의.next/cache도 모노레포의 어느 깊이에 있든(apps/web/.next/cache) 남겨요. 다음next build는 거기서 시작하므로 캐시 단계가 필요 없고No Cache Detected도 나오지 않아요..next의 나머지와 체크아웃의 다른 추적되지 않는 파일은 작업이 끝날 때마다 정리돼요.actions/cache복원이 머신을 읽어요. 저장한 것은 리포지토리당 GitHub의 10 GB보다 넓은 공간에 머신 옆에 남고, 복원은 로컬 읽기예요..next/cache단계는 새 VM에서 도는 작업을 위해 남겨 둘 수 있어요. 전용 머신에서는 복원이 남겨 둔 캐시를 덮어쓰지 않아요.- 정액으로 더 많은 코어. 컴파일과 정적 페이지 생성이 그 코어를 쓰고, 실행 시간은 무제한이에요.
| 레이블 | 머신 | 요금제 |
|---|---|---|
skipbox | 4 vCPU · 16 GB | S, 월 $39 |
skipbox-8x16 | 8 vCPU · 16 GB | M, 월 $79 |
skipbox-16x32 | 16 vCPU · 32 GB | L, 월 $149 |
옮기는 건 한 줄이에요
jobs:
build:
runs-on: skipbox-8x16 # was ubuntu-latest
env:
NODE_OPTIONS: --max-old-space-size=12288
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- uses: actions/cache@v4
with:
path: ${{ github.workspace }}/.next/cache
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
restore-keys: |
${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
- run: npm ci
- run: npx next build
skipbox-8x16은 M 요금제에서 돌고, 무료 체험은 runs-on: skipbox를 돌려요.
- GitHub로 Skipbox에 로그인하세요.
- Skipbox GitHub App을 설치하고 리포지토리를 고르세요.
runs-on을 바꾸고 푸시하세요.
보안
- 머신은 내 계정만 써요. 다른 회사의 작업은 그 머신에서 돌지 않아요.
- 작업이 끝날 때마다 실행기의 자격 증명, 프로세스, 컨테이너를 지우고, 남겨 둔 체크아웃의 git 자격 증명과,
.next/cache같은 빌드 캐시를 뺀 추적되지 않는 파일도 지워요. ‘작업마다 새 VM’을 켜면 작업마다 새 머신에서 돌아요. - 쓰기 권한이 없는 사람의 코드(포크에서 온 풀 리퀘스트 등)는 새 VM에서 돌고, 그 VM은 캐시를 읽을 수만 있고 바꿀 수는 없어요.
자세한 내용은 작업을 분리하는 방식에 있어요.
Next.js 빌드로 체험해 보세요
무료 체험은 7일 또는 작업 시간 3,000분 중 먼저 끝나는 쪽까지 무료이고, 카드가 필요 없어요. runs-on: skipbox를 16 GB로 돌리니, 프라이빗 리포지토리 ubuntu-latest의 2배 메모리예요. 그곳에서 캐시와 메모리를 시험하고, 더 필요한 빌드는 L 요금제(skipbox-16x32, 32 GB)로 옮기세요.
자주 묻는 질문
GitHub Actions에서 next build가 왜 느린가요?
대개 .next/cache가 비어 있는 채로 시작하기 때문이에요. Next.js는 빌드 캐시를 .next/cache에 저장하고 다음 빌드에서 다시 쓰는데, GitHub 호스팅 작업은 새 VM이므로 .next/cache를 이어 주는 단계가 없으면 모든 빌드가 콜드 빌드가 되고, 로그에 No Cache Detected 경고가 나와요. 잠금 파일과 소스 파일을 키로 하는 .next/cache용 actions/cache를 더하세요. 나머지 시간은 2 CPU에서의 설치와 컴파일이에요.
GitHub Actions에서 Next.js 빌드에는 어떤 크기의 실행기를 써야 하나요?
빌드의 최대치에 충분한 메모리예요. 프라이빗 리포지토리의 ubuntu-latest는 CPU 2개와 8 GB이고, 큰 Next.js 앱의 webpack 빌드, 타입 검사, 소스 맵은 그것을 넘을 수 있어요. GitHub의 대형 실행기는 4코어가 16 GB, 8코어가 32 GB이고, GitHub Team이나 Enterprise Cloud에서만, 분 단위로 쓸 수 있어요. Skipbox는 runs-on: skipbox-8x16에서 8 vCPU와 16 GB를 월 $79에, skipbox-16x32에서 16 vCPU와 32 GB를 $149에 줘요.
GitHub Actions의 Next.js 빌드에서 JavaScript heap out of memory는 어떻게 고치나요?
그 오류는 머신의 메모리가 아니라 Node 자체의 힙 한도예요. NODE_OPTIONS=--max-old-space-size=<MiB>로, 머신의 메모리보다 낮게 올리세요. 그 뒤 작업이 대신 exit code 137로 끝난다면 머신 자체의 메모리가 바닥난 거예요. 빌드의 메모리를 줄이거나(experimental.webpackMemoryOptimizations, 프로덕션 소스 맵 끄기) 메모리가 더 많은 머신에서 돌리세요.
Next.js 빌드의 메모리 사용량은 어떻게 줄이나요?
Next.js의 메모리 가이드에 따르면, experimental.webpackMemoryOptimizations(v15 이상)를 써 보고, webpack 빌드 워커를 켜 두고(v14.1.0부터 사용자 webpack 설정이 없으면 기본값), productionBrowserSourceMaps와 experimental.serverSourceMaps를 끄고, next build --experimental-debug-memory-usage로 측정하세요. typescript.ignoreBuildErrors로 타입 검사를 건너뛰면 메모리는 줄지만 타입 오류가 통과하므로, 다른 CI 작업이 타입을 검사할 때만 그렇게 하세요.
Skipbox는 작업 사이에 .next/cache를 남기나요?
네. 전용 머신은 작업 사이에 체크아웃을 남기고, 그 안의 .next/cache도 Next.js가 둔 자리(모노레포라면 apps/web/.next/cache)에 그대로 남겨요. 그래서 다음 next build는 캐시 단계 없이 지난 빌드의 캐시에서 시작해요. .next의 나머지와 체크아웃의 다른 추적되지 않는 파일은 작업이 끝날 때마다 정리돼요. npm이나 pnpm의 캐시, setup-node가 설치한 Node 버전, Docker의 레이어도 디스크에 남아요. .next/cache용 actions/cache 단계는 그대로 둬도 돼요. 포크에서 온 풀 리퀘스트처럼 새 VM에서 도는 작업은 거기서 복원하고, 전용 머신에서는 복원이 남겨 둔 캐시를 덮어쓰지 않아요.
체험하는 데 비용이 얼마나 드나요?
들지 않아요. 무료 체험은 7일 또는 작업 시간 3,000분 중 먼저 끝나는 쪽까지이고, 카드가 필요 없으며, 4 vCPU와 16 GB로 돌아요. 프라이빗 리포지토리 ubuntu-latest의 8 GB의 2배이고, GitHub의 4코어 대형 실행기와 같아요. 캐시와 메모리를 그곳에서 시험하고, 더 필요한 빌드라면 L 요금제를 고르고 레이블을 skipbox-16x32(32 GB)로 바꾸세요.
2026년 11월 16일 업데이트