정적 내보내기로 서버 없애기

빌드 결과가 순수 HTML·CSS·JavaScript가 돼

output: 'export'를 설정하면 next build가 out/ 디렉터리에 정적 파일을 만들어. S3, GitHub Pages, Cloudflare Pages, 평범한 nginx처럼 서버 코드를 실행하지 않는 호스트에도 그대로 올릴 수 있어.

작동하는 것	작동하지 않는 것
빌드 시점 서버 컴포넌트	서버 액션
정적인 GET 라우트 핸들러	Proxy와 동적 라우트 핸들러
클라이언트 컴포넌트와 SWR	ISR와 요청형 재검증
`generateStaticParams`	`cookies()`, `headers()`
사용자 loader를 둔 `next/image`	기본 이미지 optimizer

서버가 필요 없는 제품에만 맞아

마케팅 사이트, 문서, 포트폴리오처럼 콘텐츠가 빌드 때 확정되는 곳에는 가장 싸고 단순한 배포가 돼. 요청별 개인화나 앱 내부 변경이 필요하다면 정적 export에 억지로 맞추기보다 서버 실행 환경을 선택해.

동적 데이터는 브라우저 책임이 돼

SWR로 외부 API를 읽을 수는 있지만 API의 CORS, 인증, 가용성이 모두 사용자 브라우저에 드러나. 서버 기능을 잃는 대가를 배포비 절감과 함께 계산해야 해.

정적 export 후보에서 요청별 API를 목록으로 만들고 각각 빌드 시점 데이터, 브라우저 API, 외부 서비스 중 어디로 옮길지 정해. out/을 로컬 정적 서버와 실제 CDN에서 열어 새로고침·깊은 링크·404·asset base path를 확인해. 이미지 loader와 cache header도 호스트 계약에 맞춰. 정적 호스트의 경로 규칙은 서로 다르므로 확장자 없는 주소와 후행 슬래시를 함께 시험해. 로컬에서 열린 파일이 CDN 새로고침에서도 같은 응답을 준다는 보장이 필요해.

서버 비용 0이라는 장점이 backend 책임 0을 뜻하지 않아. 폼, 검색, 인증을 외부 API로 보내면 그 서비스의 비용과 장애가 제품에 남아. 단지 Next.js 서버가 없어진 거야. 정적 export는 콘텐츠 경계가 실제로 정적일 때 가장 강해. 정적 export build에서 cookies·동적 handler·기본 이미지 optimizer를 각각 사용해 실패를 확인해. 완성된 out/을 실제 정적 호스트에 올리고 루트·중첩 라우트 새로고침·404·asset 경로·클라이언트 API 실패를 점검해 서버 없는 경계를 증명해.

Code

정적 export 설정하고 빌드하기·ts

// next.config.ts
import type { NextConfig } from 'next';
const config: NextConfig = {
  output: 'export',
  trailingSlash: true,    // 선택: /about/ 대신 /about
  images: { unoptimized: true }, // 또는 사용자 정의 loader
};
export default config;

빌드하기·bash

npm run build

# 출력:
# out/
# ├── index.html
# ├── about/index.html
# ├── blog/post-1/index.html
# └── _next/...

# 배포:
npx serve out                # 로컬 테스트
aws s3 sync out s3://bucket   # 프로덕션

빌드 결과가 순수 HTML·CSS·JavaScript가 돼

서버가 필요 없는 제품에만 맞아

동적 데이터는 브라우저 책임이 돼

Code

External links

Exercise

Progress

댓글 0