배포(Deploying)

배포(Deploying)

Next.js는 Node.js 서버, Docker 컨테이너, 정적 export, 그리고 어댑터(adapter)를 통한 여러 플랫폼 배포를 지원해요. 어떤 방식이 어떤 기능을 지원하는지 알고, 상황에 맞는 배포 방법을 고르면 돼요. 여기서는 주요 배포 방식을 정리할게요.

출처: https://nextjs.org/docs/app/getting-started/deploying

배포 옵션 기능 지원
Node.js 서버 전체
Docker 컨테이너 전체
정적 export 제한적
어댑터 다양 (검증된 어댑터는 테스트 스위트를 통과)

Node.js 서버

Node.js를 지원하는 어떤 제공자에든 배포할 수 있어요. package.json에 "build"와 "start" 스크립트가 있는지 확인하세요.

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

그런 다음 npm run build로 애플리케이션을 빌드하고 npm run start로 Node.js 서버를 시작해요. 이 서버는 Next.js의 모든 기능을 지원해요. 필요하면 커스텀 서버로 전환할 수도 있어요. Flightcontrol, Railway, Replit, Hostinger 같은 제공자용 템플릿이 제공돼요.

Docker

Next.js는 Docker 컨테이너를 지원하는 어떤 제공자에도 배포할 수 있어요. Kubernetes 같은 컨테이너 오케스트레이터나 Docker를 실행하는 클라우드 제공자를 포함해요. 컨테이너화 모범 사례는 Docker 공식 Next.js·React.js 가이드에서 확인할 수 있어요.

대표적인 예시는 이래요.

  • Docker Standalone Output — output: "standalone"을 사용해 필요한 런타임 파일과 의존성만 담은 최소한의 프로덕션 준비 Docker 이미지를 생성해요.
  • Docker Export Output — output: "export"를 사용해 가벼운 컨테이너나 정적 호스팅에서 서빙할 수 있는 최적화된 HTML 파일을 생성해요.
  • Docker Multi-Environment — 서로 다른 환경 변수로 개발·스테이징·프로덕션 환경별 Docker 설정을 관리해요.

개발 중에는 Docker 대신 로컬 개발(npm run dev)을 쓰는 게 Mac·Windows에서 성능이 더 좋아요.

정적 export

Next.js는 정적 사이트나 SPA로 시작하고, 나중에 서버가 필요한 기능으로 업그레이드할 수 있게 해줘요. 정적 export를 지원하므로 HTML/CSS/JS 정적 자산을 서빙할 수 있는 어떤 웹 서버(AWS S3, Nginx, Apache 등)에도 배포할 수 있어요. 다만 정적 export로 실행 중에는 서버가 필요한 Next.js 기능을 지원하지 않아요. GitHub Pages가 대표적인 템플릿이에요.

어댑터

Next.js는 다양한 플랫폼의 인프라 역량을 지원하도록 어댑터로 변환될 수 있어요. Deployment Adapter API가 플랫폼이 Next.js 애플리케이션을 빌드·배포하는 방식을 커스터마이즈하게 해 줘요.

검증된 어댑터(Verified Adapters) 는 오픈소스이고 Next.js 호환성 테스트 스위트 전체를 통과하며 Next.js GitHub 조직 아래 호스팅돼요. Vercel과 Bun이 대표적이에요.

이 밖에 Appwrite, AWS Amplify Hosting, Cloudflare, Deno Deploy, Firebase App Hosting, Netlify 등 플랫폼이 각자의 Next.js 통합을 제공하는데, 이들은 공개 Adapter API 기반이 아니고 Next.js 팀이 검증하지 않아 기능 지원이 다를 수 있어요.

더 알아보기