Next.js는 어떤 배포 옵션과 빌드 출력을 지원하나요?

Question

Accepted Answer

Next.js는 부분적으로 **`output`** 설정으로 제어되는 여러 배포 대상을 지원합니다. 올바른 선택은 Node 서버, 컨테이너, 또는 순수 정적 호스팅이 필요한지에 따라 달라집니다.

## 빌드 출력 모드

```js
// next.config.js
module.exports = {
  // output: undefined  → 기본값: Node.js 서버 필요 (전체 기능)
  // output: "standalone" → Docker/컨테이너용 자급식 폴더
  // output: "export"     → 순수 정적 HTML/CSS/JS (서버 없음)
};
```

## 1. 기본값 (Node 서버) — 전체 기능

Node.js 서버를 실행하므로 **모든 것**을 얻습니다: SSR, ISR, Server Actions, Route Handler, 이미지 최적화, middleware. **Vercel**(Next.js 제작사, 무설정) 같은 플랫폼과 Node 호스트가 사용하는 방식입니다.

## 2. output: "standalone" — Docker / 셀프 호스팅용

```dockerfile
# Next는 필요한 파일만 .next/standalone으로 추적 → 작고 자급식인 서버
COPY --from=builder /app/.next/standalone ./
CMD ["node", "server.js"]
```

`standalone`은 실제로 사용된 의존성만 담은 최소 폴더를 만듭니다. AWS, GCP, 자체 서버 등에서 작은 Docker 이미지에 이상적입니다. 모든 서버 기능을 유지합니다.

## 3. output: "export" — 완전 정적

```text
next build → out/  (순수 HTML/CSS/JS, 어떤 정적 호스트에도 배포 가능: S3, GitHub Pages, Netlify CDN)
```

정적 export는 가장 저렴하고 단순한 호스팅을 제공하지만 **서버 기능을 비활성화**합니다: SSR 없음, ISR 없음, Route Handler 없음, Server Actions 없음, 즉석 이미지 최적화 없음. 완전 정적 사이트에만 적합합니다.

## 선택

```text
SSR/ISR/Server Actions 필요, 무설정 원함 → Vercel (또는 Node 호스트) — 기본 output
전체 기능으로 컨테이너 / 셀프 호스트 원함 → output: "standalone" + Docker
순수 정적 콘텐츠 (문서, 마케팅)            → output: "export" → 어떤 정적 CDN이든
```

## 그 밖의 고려 사항

```text
- 런타임 선택(Edge vs Node)이 함수가 어디서 실행될지에 영향을 줌
- ISR/캐싱 셀프 호스팅은 영속 저장소나 공유 캐시가 필요함
- Vercel이 아닌 호스트에서의 이미지 최적화는 커스텀 로더가 필요할 수 있음
```

## 왜 중요한가

배포는 만능 해법이 없습니다. `output` 모드가 어떤 Next.js 기능이 살아남는지 결정합니다.

**기본값/Node** 출력이 모든 서버 기능을 유지하고, **standalone**이 그것들을 Docker/셀프 호스팅용으로 패키징하며, **export**가 모든 서버 기능을 순수 정적 호스팅과 맞바꾼다는 것을 아는 것이 빌드를 인프라에 맞추고 `output: "export"`가 조용히 SSR/ISR/Server Actions를 망가뜨리는 함정을 피하게 해 줍니다.