# GitHub Actions에서 Next.js 빌드가 느리거나 메모리가 바닥날 때: 캐시, 메모리, 실행기 크기

> GitHub Actions의 Next.js 빌드는 .next/cache가 다음 실행으로 이어지지 않으면 느리고, webpack, 타입 검사, 소스 맵이 쌓이면 프라이빗 리포지토리의 8 GB ubuntu-latest에서 메모리가 바닥나요. 무엇을 캐시할지, 어떤 Next.js 설정이 메모리를 줄이는지, 그리고 실행기 크기: Skipbox에서 16 GB가 월 $79, 32 GB가 $149, .next/cache는 작업 사이에 남고 실행 시간은 무제한.

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`가 전용 머신에 남아요. 다음 빌드가 캐시 단계 없이 지난 컴파일을 다시 써요
- 16 GB가 월 $79, 32 GB가 $149. 프라이빗 `ubuntu-latest`는 8 GB
- 패키지 캐시가 내 머신에 남고, 캐시 복원은 다운로드가 아니라 그 디스크를 읽어요

**GitHub Actions를 정액으로, 실행 시간 무제한** Skipbox는 GitHub Actions 작업을 나만 쓰는 전용 머신에서 돌려요. 몇 분을 돌리든 가격은 월 $39 그대로예요. Docker 레이어와 의존성 캐시가 작업 사이에도 남아서 다음 작업이 바로 시작돼요.

4 vCPU 실행기, 매달 20,000분: GitHub $222 → Skipbox $39. 매달 $183 절약.

옮기는 데는 한 줄이면 돼요: `runs-on: skipbox`.

[7일 무료 체험 시작하기](https://app.skipbox.dev/sign-in?ref=g-nextjs-build-slow-out-of-memory-github-actions-ko)

## 느림: .next/cache가 비어 있는 채로 시작해요

Next.js의 [CI 빌드 캐시 가이드](https://nextjs.org/docs/app/guides/ci-build-caching)에 따르면, Next.js는 빌드 사이에 공유되는 캐시를 `.next/cache`에 저장하고, 빌드 사이에 그것을 유지하지 않는 CI는 `No Cache Detected` 오류를 보여 줘요. 가이드의 GitHub Actions 단계는 이래요.

```yaml
- 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 가이드](https://turborepo.dev/docs/guides/ci-vendors/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의 [메모리 사용 가이드](https://nextjs.org/docs/app/guides/memory-usage)에서:

- **`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 조직, 분 단위([대형 실행기](https://docs.github.com/en/actions/concepts/runners/larger-runners)) |
| 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 |

## 옮기는 건 한 줄이에요

```yaml
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은 캐시를 읽을 수만 있고 바꿀 수는 없어요.

자세한 내용은 [작업을 분리하는 방식](https://docs.skipbox.dev/ko/isolation)에 있어요.

## 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 업데이트 · https://skipbox.dev/ko/guides/nextjs-build-slow-out-of-memory-github-actions
