Next.js Deploying 정리

Next.js Docs – Getting Started: Deploying 페이지를 기반으로, App Router 환경에서 Next.js 애플리케이션 배포 방법을 정리한 문서입니다. citeturn0search2

1. 개요

Next.js 애플리케이션은 크게 두 가지 방식으로 배포할 수 있습니다. citeturn0search2

Managed Next.js (Vercel 사용)
Self-hosting (직접 호스팅)
- Node.js 서버
- Docker 이미지
- Static HTML Export (정적 사이트/SPA)

공식 문서 기준으로, next build를 통해 생성되는 표준 빌드 결과물은
Vercel 및 자체 호스팅 환경 모두에서 동일하게 사용되며,
Next.js의 모든 기능을 지원하도록 설계되어 있습니다. citeturn0search2

2. Production Build

프로덕션 배포 전에는 항상 프로덕션 빌드를 생성해야 합니다.

npm run build
# 또는
yarn build
# 또는
pnpm build

next build 실행 시 다음과 같은 작업이 수행됩니다. citeturn0search2

각 페이지/라우트 기준으로 HTML, CSS, JS 번들 생성
Next.js Compiler를 사용해 JS 번들을 최적화 및 압축(minify)
최신 브라우저 호환성을 고려한 빌드 출력 생성
결과적으로, 관리형(Vercel)·자체 호스팅 모두에서 동일한 형식의 배포 아티팩트가 생성됨

빌드가 완료되면, 일반적인 self-host 환경에서는 다음과 같이 서버를 실행합니다.

npm run start
# 내부적으로
# next start

next start로 실행되는 Node.js 서버는 Next.js의 모든 기능을 지원합니다. citeturn0search2

3. Managed Next.js with Vercel

Next.js를 만든 Vercel에서는 Next.js 전용 관리형 인프라와 개발자 경험을 제공합니다. citeturn0search2turn0search7

3.1 특징

Zero-configuration 배포: 별도 설정 없이도 바로 배포 가능
자동 스케일링, 고가용성, 전역 CDN 및 캐싱 등 성능 최적화
GitHub/GitLab/Bitbucket 연동 시
- PR마다 Preview URL 자동 생성
- main/master 브랜치에 머지 시 자동 프로덕션 배포

3.2 기본 배포 흐름 (개요)

Next.js 프로젝트를 Git 리포지토리에 푸시
Vercel 대시보드에서 리포지토리 연결
프레임워크로 Next.js 선택 (대부분 자동 감지)
vercel CLI를 사용해 로컬에서 배포 시작도 가능

Vercel이 아닌 자체 호스팅과 비교해도, Next.js 기능 지원 측면에서는 동일하며
인프라 관리(스케일링, 글로벌 배포 등)를 Vercel이 대신해준다고 생각하면 이해하기 쉽습니다. citeturn0search2turn0search7

4. Self-Hosting (직접 호스팅)

Self-hosting은 직접 서버/인프라를 구성하여 Next.js를 운영하는 방식입니다. citeturn0search2

4.1 공통 준비 사항

package.json에는 최소한 다음 스크립트가 있어야 합니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

배포 절차 개요

코드 배포 (Git pull, CI/CD 등으로 서버에 반영)
npm install 또는 pnpm install 등으로 의존성 설치
npm run build로 프로덕션 빌드 생성
npm run start로 서버 실행 (보통 PM2, systemd, Docker 등으로 관리)

4.2 Node.js 서버 배포

가장 기본적인 형태의 self-host 방식입니다. citeturn0search2

대상: Node.js를 지원하는 어떤 호스팅 서비스든 가능
- 예: AWS EC2, GCP Compute Engine, DigitalOcean Droplet 등
장점:
- Next.js 기능 전체 지원 (Server Components, Route Handlers, Proxy, Image Optimization, ISR 등)
- Custom server 구성도 가능 (예: Express와 함께 사용) – 다만 권장 패턴은 next start 사용

요약 흐름:

서버에 Node.js 설치
애플리케이션 코드 및 .next 빌드 결과를 서버에 배포
npm run start로 애플리케이션 실행
Nginx/Apache 등을 앞단 리버스 프록시 및 SSL 종료 용도로 구성

4.3 Docker Image 배포

Next.js를 Docker 컨테이너로 패키징하여 배포하는 방식입니다. citeturn0search2

대상:
- Kubernetes, ECS, Cloud Run, Docker Swarm, 단일 Docker 호스트 등
장점:
- 환경(런타임, 의존성, OS 레벨)을 이미지로 고정하여 재현성 높은 배포 가능
- 인프라 설정을 코드(Dockerfile, compose, Helm 등)로 관리할 수 있음

문서에서 안내하는 기본 흐름: citeturn0search2

Docker 설치
Next.js Docker 예제(또는 multi-env 예제) 프로젝트 클론
컨테이너 빌드:
```
docker build -t nextjs-docker .
```
컨테이너 실행:
```
docker run -p 3000:3000 nextjs-docker
```

컨테이너 내부에서는 보통 다음과 같이 실행됩니다.

npm run build
npm run start

이 방식 역시 Next.js 기능 전체 지원입니다.

4.4 Static HTML Export

Next.js를 정적 사이트(Static Site) 또는 SPA처럼 배포하는 방식입니다. citeturn0search2turn0search0

특징:
- next export를 통해 HTML/CSS/JS 정적 자산을 생성
- S3, Nginx, Apache, GitHub Pages 등 어떤 정적 호스팅에도 올릴 수 있음
제약:
- 서버가 필요한 기능(예: 일부 동적 Route Handlers, 서버 측 데이터 변환, 서버 액션 등)은 사용할 수 없음
- 즉, 서버 의존 기능은 비활성화 필요
장점:
- 서버 운영 없이 정적 파일만 서빙하므로 인프라 구성이 단순하고, 비용도 저렴

참고: App Router 기반에서도 일부 Server Components는 static export와 함께 사용할 수 있음이 문서에 언급되어 있습니다. (단, 서버 기능 의존 여부에 따라 제약 존재) citeturn0search2turn0search8

5. Image Optimization 관련 사항

next/image를 사용한 Image Optimization은 self-host 환경에서도 next start만 사용하면 추가 설정 없이 동작합니다. citeturn0search2

권장 사항:
- sharp 패키지 설치:
```
npm install sharp
```
- 특히 Linux 환경에서 성능 및 메모리 사용 최적화에 도움이 됩니다.
Static export와 함께 사용하려면
- next.config.js의 images.loader 설정을 통해 커스텀 이미지 로더를 지정해야 합니다.
- 이 경우 이미지 최적화는 빌드 시점이 아니라 런타임에 수행됩니다. citeturn0search2

이미지 캐싱 동작 및 TTL 설정 등은 Image Optimization 관련 문서를 추가로 참고해야 합니다.

6. 배포 전략 설계 팁

Next.js 앱 배포 방식을 선택할 때 다음 기준을 고려하면 좋습니다.

인프라 관리 여력
- 서버/컨테이너/네트워크를 직접 관리하기 어려우면: Vercel 또는 다른 관리형 플랫폼 고려
- 이미 Kubernetes, Docker 기반 인프라가 있다면: Docker Image + Self-hosting
필요한 기능 범위
- 서버 기능(SSR, Route Handlers, Proxy, 서버 액션, 고급 캐싱) 모두 활용:
  - Node.js 서버 또는 Docker 기반 self-host, 혹은 Vercel
- 간단한 정적 페이지/블로그/랜딩 페이지:
  - Static HTML Export + 정적 호스팅(S3, GitHub Pages 등)
트래픽 패턴과 확장성
- 트래픽 급변, 글로벌 유저 대상:
  - Vercel과 같은 매니지드 플랫폼의 자동 스케일링, 전역 CDN 장점 활용
- 내부 시스템, 관리용 대시보드 등 트래픽 예측 가능:
  - 자체 호스팅도 충분히 고려 가능
DevOps/CI-CD 환경
- Git 기반 워크플로우, PR Preview, 실험적인 배포가 중요하다면:
  - Vercel, Netlify, Cloudflare 등과의 연동을 활용
- 사내 CI/CD 파이프라인(Jenkins, GitHub Actions, GitLab CI 등)을 이미 사용 중이라면:
  - next build + Docker 빌드 + 자체 배포 파이프라인 구성

# Next.js Deploying 정리