Skipbox

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/**").

메모리 부족: 서로 다른 두 오류

힙을 머신의 메모리보다 높이면 첫 번째 오류가 두 번째 오류로 바뀌어요.

메모리를 덜 쓰기: 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는 하지 말라고 경고해요.

메모리가 더 많은 머신 쓰기

월 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에서 도는 작업을 위해 남겨 둘 수 있어요. 전용 머신에서는 복원이 남겨 둔 캐시를 덮어쓰지 않아요.
  • 정액으로 더 많은 코어. 컴파일과 정적 페이지 생성이 그 코어를 쓰고, 실행 시간은 무제한이에요.

옮기는 건 한 줄이에요

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를 돌려요.

  1. GitHub로 Skipbox에 로그인하세요.
  2. Skipbox GitHub App을 설치하고 리포지토리를 고르세요.
  3. 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일 업데이트

캐시가 늘 살아 있는 더 빠른 CI/CD

캐시가 남는 전용 실행기를 정액으로

머신은 Skipbox가 준비해요. 바꿀 건 한 줄뿐이에요. 최대로 쓰면 비용은 GitHub의 1/12. 정액이라 하루 종일 돌려도 돼요. 캐시 용량은 GitHub의 7배.

  • 카드 불필요
  • GitHub로 로그인
  • 언제든 해지