Next.js out 폴더를
정적 사이트로 공개하세요
Next.js 앱을 정적 HTML과 assets로 export하고 out 디렉터리를 업로드하세요. Node.js 서버를 실행하지 않고 전 세계에 게시할 수 있습니다.
Static export 지원 매트릭스
out을 업로드하기 전에 앱이 static export 모델에 맞는지 확인하세요.
잘 맞음
- build 시점에 생성되는 정적 routes
- 정적으로 렌더링할 수 있는 App Router 페이지
- Pages Router getStaticProps / getStaticPaths
- hydration 이후 client-side data fetching
- next/link, dynamic imports, CSS Modules, 정적 assets
다른 runtime 필요
- 서버 실행이 필요한 API routes와 route handlers
- Middleware, rewrites, redirects, custom headers
- getServerSideProps와 request-time rendering
- Incremental Static Regeneration
- 별도 static 전략이 없는 기본 next/image 최적화
서버가 아니라 framework가 필요할 때 Next.js를 사용하세요
framework는 유지하고 서버는 덜어내기
Next.js static export를 쓰면 file-based routing, layout, metadata, build-time rendering, CSS 지원, 필요한 client-side React를 그대로 가져갈 수 있습니다.
최종 output은 여전히 파일입니다. 마케팅 사이트, 문서, 포트폴리오, 제품 페이지, content hub처럼 build 시점에 준비할 수 있는 페이지에 잘 맞습니다.
정적 asset처럼 빠르게
미리 렌더링된 HTML은 공격적으로 캐시하고 render server를 기다리지 않고 바로 제공할 수 있습니다.
운영 부담 감소
Node runtime이 없으면 움직이는 부분이 줄고, deploy artifact가 단순해지며 build 사이의 production drift도 줄어듭니다.
runtime 경계 명확화
페이지에 서버 코드가 필요하다면 static export로 억지로 밀어 넣지 않아야 합니다. 미리 빌드할 수 있다면 out 디렉터리가 깔끔한 게시 artifact입니다.
Static export에서 자주 막히는 지점
server-only 기능 때문에 build가 실패합니다
export되는 route에서 request-time API를 제거하고 별도 backend로 옮기거나, 해당 부분을 server runtime을 지원하는 플랫폼에 배포하세요.
이미지는 dev에서 보이지만 export 후 실패합니다
기본 next/image optimizer는 서버를 기대합니다. images.unoptimized, custom loader 또는 일반 정적 이미지 assets를 사용하세요.
dynamic routes가 누락됩니다
App Router의 generateStaticParams 또는 Pages Router의 getStaticPaths로 build 시점에 route 목록을 생성하세요.
redirects 또는 rewrites가 적용되지 않습니다
Next.js redirects와 rewrites는 static export 결과물에 포함되지 않습니다. 정적 페이지 구조, client-side navigation 또는 사용 가능한 platform-level redirects를 사용하세요.
Next.js static export 체크리스트
output: 'export' 설정
next start나 호스팅된 Node runtime을 기대하지 않고 build 시점에 정적 HTML을 생성하도록 Next.js에 지정합니다.
output: 'export'/out build 및 확인
production build를 실행하고 out 디렉터리에 렌더링된 페이지, assets, 404 페이지, 게시할 정적 파일이 들어 있는지 확인합니다.
npm run build업로드 후 routes 테스트
out 디렉터리를 업로드한 뒤 중첩 경로, 정적 assets, unoptimized images가 게시된 사이트에서 정상인지 확인합니다.
자주 묻는 질문
Next.js Image 컴포넌트가 export 후 실패하는 이유는 무엇인가요?
기본 Image 최적화 파이프라인은 서버를 기대합니다. static export에서는 next.config.js에서 images.unoptimized를 true로 설정해야 합니다.
API routes나 getServerSideProps도 동작하나요?
아니요. static export는 API routes, middleware, getServerSideProps 같은 서버 런타임 기능을 제거합니다. 해당 로직은 별도 백엔드나 서버리스 서비스로 옮기세요.
App Router를 사용할 수 있나요?
정적으로 렌더링할 수 있고 headers, cookies처럼 동적 서버 전용 API에 의존하지 않는 route라면 가능합니다.
동적 콘텐츠는 어떻게 처리하나요?
가능하면 빌드 시점에 가져오거나, 페이지 hydrate 이후 클라이언트에서 불러오세요. static export는 HTML을 미리 준비할 수 있을 때 가장 잘 맞습니다.
.next와 out 중 무엇을 올려야 하나요?
output: 'export' 기준으로는 out을 올립니다. .next는 Next.js 내부 빌드 디렉터리이며 공개할 static export 결과물이 아닙니다.
Vercel의 Next.js 호스팅을 대체하나요?
모든 Next.js 앱이 아니라 static export에 맞는 선택지입니다. SSR, middleware, ISR, server actions, API routes에 의존한다면 해당 기능을 지원하는 런타임이 필요합니다.