Deploying

Next.js는 Node.js 서버, Docker 컨테이너, 정적 내보내기(Static export) 형태로 배포할 수도 있고, 다양한 호스팅 플랫폼 환경에 맞춰 조정(어댑터 활용)해서 실행할 수도 있습니다. 정말 유연하죠?

배포 옵션 (Deployment Option)	기능 지원 범위 (Feature Support)
Node.js 서버 (Node.js server)	전부 지원 (All)
Docker 컨테이너 (Docker container)	전부 지원 (All)
정적 내보내기 (Static export)	제한적 지원 (Limited)
어댑터 (Adapters)	플랫폼에 따라 다름 (Platform-specific)

💡 강사님의 꿀팁:
처음 배포를 접하시면 이 표가 조금 와닿지 않을 수 있어요. 간단히 말해서 여러분의 프로젝트가 단순히 보여주기만 하는 페이지라면 '정적 내보내기'도 괜찮지만, Next.js의 강력한 기능인 서버 사이드 렌더링(SSR)이나 API 라우트 등을 쓰려면 'Node.js 서버'나 'Docker', 혹은 Vercel 같은 전용 '어댑터' 환경이 필요하다는 뜻입니다.

Node.js 서버 (Node.js server)

Next.js는 Node.js를 지원하는 어떤 호스팅 제공자(provider)에게든 배포할 수 있습니다. 배포하기 전에 여러분의 프로젝트 폴더에 있는 package.json 파일에 "build"와 "start" 스크립트가 잘 설정되어 있는지 꼭 확인해 주세요!

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

확인이 끝났다면, 터미널에서 npm run build 명령어를 실행해서 여러분의 애플리케이션을 배포용으로 빌드(최적화)합니다. 그 다음 npm run start 명령어를 실행하면 Node.js 서버가 켜지게 되죠.

이 Node.js 서버는 Next.js가 자랑하는 모든 기능을 완벽하게 지원합니다. 만약 여러분의 입맛에 맞게 서버를 완전히 뜯어고치고 싶다면, 기본 서버 설정에서 벗어나 커스텀 서버(Custom server) 방식으로 전환해서 사용할 수도 있답니다.

Node.js 배포 환경은 Next.js의 모든 기능을 지원합니다. 여러분이 구축한 인프라 환경에 맞춰 서버를 직접 호스팅하고 설정하는 방법(Self-hosting)도 꼭 한 번 읽어보시길 권장해요.

템플릿 (Templates)

아래는 Node.js 환경으로 배포할 때 참고하기 좋은 템플릿들입니다.

• Flightcontrol
• Railway
• Replit
• Hostinger

Docker

Next.js는 Docker 컨테이너를 지원하는 곳이라면 어디든 배포할 수 있습니다. 여기에는 쿠버네티스(Kubernetes) 같은 거대한 컨테이너 오케스트레이션 도구부터, Docker 컨테이너를 그대로 실행시켜 주는 다양한 클라우드 서비스들이 모두 포함됩니다. 앱을 컨테이너로 예쁘게 포장하는(Containerization) 모범 사례를 알고 싶으시다면 React.js를 위한 Docker 가이드를 참고해 보세요.

Docker 배포 역시 Next.js의 모든 기능을 전부 지원합니다. 여러분의 인프라에 맞춰 설정하는 방법을 배워보세요.

개발 시 주의사항 (Note for development): Docker가 실제 서비스(프로덕션) 환경에 배포할 때는 정말 훌륭한 도구입니다. 하지만 맥(Mac)이나 윈도우(Windows) 컴퓨터에서 한창 코드를 짜며 개발을 진행하실 때는, 성능이 느려질 수 있으니 Docker보다는 일반적인 로컬 개발 환경(npm run dev)을 사용하는 것을 더 추천해 드려요. 로컬 개발 환경을 최적화하는 방법도 더 자세히 알아보실 수 있습니다.

템플릿 (Templates)

다음 예제들은 Next.js 애플리케이션을 Docker 컨테이너로 만들 때의 모범 사례들을 보여줍니다:

• Docker 독립 실행형 출력 (Docker Standalone Output) - output: "standalone" 설정을 사용해서 배포하는 방법이에요. 실행에 꼭 필요한 런타임 파일과 의존성들만 쏙쏙 골라내서 아주 가볍고 실무에 바로 쓸 수 있는(production-ready) Docker 이미지를 만들어 냅니다.
• Docker 내보내기 출력 (Docker Export Output) - output: "export" 설정을 사용해서 완전히 정적인(Static) Next.js 애플리케이션을 배포하는 방법입니다. 가벼운 웹 서버 컨테이너나 정적 호스팅 환경에서 빠르게 제공할 수 있도록 최적화된 HTML 파일들을 만들어 내죠.
• Docker 다중 환경 (Docker Multi-Environment) - 개발(development), 스테이징(staging), 프로덕션(production) 등 다양한 환경에 맞춰 각기 다른 환경 변수(Environment variables)를 가지도록 Docker 설정을 나누어 관리하는 방법입니다.

추가로, 유명한 호스팅 제공업체들에서도 Next.js를 Docker로 배포하는 가이드를 제공하고 있으니 참고해 보세요:

• DigitalOcean
• Fly.io
• Google Cloud Run
• Render
• SST

💡 강사님의 면접 대비 꿀팁:
기술 면접이나 임원 면접을 준비하시다 보면 "본인이 만든 프로젝트를 어떻게 배포했나요? 배포 파이프라인은 어떻게 되나요?"라는 질문을 자주 받게 됩니다. 이때 단순히 "호스팅 사이트에 연결해서 버튼 하나 눌렀어요"라고 답변하는 것보다, "Docker를 이용해 standalone 방식으로 컨테이너 이미지를 최적화하여 빌드하고, 이를 클라우드에 배포해 보았습니다"라고 답변하면 인프라에 대한 이해도를 보여줄 수 있어 면접관분들에게 아주 매력적으로 다가갈 수 있습니다!

정적 내보내기 (Static export)

Next.js를 사용하면, 처음에는 단순한 정적 웹사이트나 싱글 페이지 애플리케이션(SPA) 형태로 가볍게 시작할 수 있어요. 그러다가 나중에 프로젝트가 커져서 서버의 힘이 필요해지면 언제든지 관련 기능을 사용하도록 업그레이드할 수 있답니다.

Next.js는 정적 내보내기(Static exports) 기능을 완벽하게 지원합니다. 즉, HTML, CSS, JS 같은 정적 파일들을 서비스할 수 있는 웹 서버라면 그 어떤 곳이든 배포하고 호스팅할 수 있다는 뜻이죠. AWS S3 버킷이나, Nginx, Apache 같은 웹 서버들이 대표적인 예입니다.

하지만 주의하실 점이 있어요! 정적 내보내기 방식으로 실행할 때는, 반드시 서버가 있어야만 동작하는 Next.js의 특정 기능들은 사용할 수 없습니다. (예: Image 컴포넌트의 기본 이미지 최적화, 동적 API 라우트 등) 어떤 기능들이 지원되지 않는지 여기서 자세히 알아보세요.

템플릿 (Templates)

정적 호스팅의 대표주자죠!

• GitHub Pages

어댑터 (Adapters)

Next.js는 각기 다른 배포 플랫폼들이 가진 고유한 인프라 기능들을 100% 활용할 수 있도록, '어댑터(Adapter)'를 통해 맞춤형으로 실행될 수 있습니다.

각 제공업체별로 지원하는 Next.js의 기능(예: Edge Runtime 지원 여부 등)이 조금씩 다를 수 있으니, 아래의 각 공식 문서를 꼭 참고해 보시길 바랍니다:

• Appwrite Sites
• AWS Amplify Hosting
• Cloudflare
• Deno Deploy
• Firebase App Hosting
• Netlify
• Vercel (Next.js를 만든 Vercel답게 설정 없이 가장 완벽한 호환성을 보여줍니다)

참고 (Note): 현재 저희(Next.js 팀)는 모든 플랫폼들이 표준적으로 도입할 수 있는 배포 어댑터 API (Deployment Adapters API)를 열심히 개발하고 있습니다. 이 작업이 모두 완료되면, 여러분만의 고유한 커스텀 어댑터를 작성하는 방법에 대한 문서도 추가로 제공할 예정입니다.

---

전체 문서의 의미론적 구조(마인드맵이나 개요 형태)를 한눈에 파악하고 싶으시다면 https://nextjs.org/docs/sitemap.md 파일을 확인해 주세요.

현재 이용 가능한 모든 문서들의 색인(Index) 리스트가 필요하시다면 https://nextjs.org/docs/llms.txt 파일에서 확인하실 수 있습니다.