🏠 Next.js App Router Self‑Hosting 완벽 가이드

 

🏠 Next.js App Router Self‑Hosting 완벽 가이드

Next.js는 Vercel에 최적화되어 있지만, 자체 서버(Node.js, Docker, CDN 등)에서도 강력하게 작동할 수 있도록 설계되어 있습니다. 이 글에서는 App Router 기반 프로젝트를 스스로 호스팅할 때 알아야 할 모든 내용을 정리합니다.

---

🛠 1. 실행 방식 선택

Node.js 서버 실행

npm run build
npm run start

• next start는 production 모드 실행
• 모든 기능(SSR, API Route, 이미지 최적화 등) 사용 가능

Docker 컨테이너

• next build → 이미지 생성 후 컨테이너화
• Kubernetes, AWS ECS, GCP 등에서 사용 가능

정적 사이트 내보내기

• next export 명령으로 생성
• 단, API Routes, SSR, ISR은 작동하지 않음

---

🖼️ 2. 이미지 최적화 (next/image)

• 기본 이미지 최적화 기능은 서버 내 sharp을 통해 수행됨
• 서버에 sharp이 없으면 성능이 제한될 수 있음
• 커스텀 로더를 지정해 외부 이미지 최적화 서비스 연결도 가능

---

🔑 3. 환경 변수 설정

• .env, .env.production 등으로 구성
• 클라이언트에 노출하려면 NEXT_PUBLIC_ 접두사 필수

DATABASE_URL=...
NEXT_PUBLIC_API_URL=https://...

---

⚡ 4. 캐시 핸들링 (ISR 등)

반응형

Next.js는 기본적으로 파일 시스템 기반 캐시를 사용합니다.

복수 인스턴스를 운영하거나 클러스터 환경(Kubernetes 등)에서 캐시 공유가 필요하다면 커스텀 캐시 핸들러를 설정해야 합니다.

// next.config.js
module.exports = {
  cacheHandler: require.resolve('./my-cache-handler.js'),
  cacheMaxMemorySize: 0,
};

• Redis, S3 등 외부 스토리지를 사용할 수 있습니다.

---

☁️ 5. CDN 구성

• 정적 자산 (/_next/static/)은 CDN을 통해 서빙
• ISR 사용 시 stale-while-revalidate 캐시 정책을 지원하는 CDN 필요
• 예: AWS CloudFront, Fastly, Cloudflare

---

🚿 6. 스트리밍 & 프록시 설정

App Router는 서버 스트리밍 기능을 적극 활용합니다. 이를 위해 프록시(Nginx 등)에서 buffering 비활성화가 필요할 수 있습니다.

proxy_buffering off;

---

🧬 7. 빌드 ID 관리 (빌드 간 버전 정합성)

여러 서버 인스턴스 간 자산 불일치 문제를 방지하기 위해 generateBuildId를 설정할 수 있습니다:

// next.config.js
module.exports = {
  generateBuildId: async () => process.env.GIT_COMMIT_SHA || 'default',
};

---

🧹 8. 종료 시그널 처리 (Graceful Shutdown)

Docker 또는 Kubernetes 환경에서는 SIGTERM, SIGINT 시그널을 수신해 서버를 정리 종료하는 코드가 필요합니다:

NEXT_MANUAL_SIG_HANDLE=true npm run start

process.on('SIGTERM', () => {
  console.log('SIGTERM received, closing...');
  server.close();
});

---

✅ 전체 체크리스트 요약

항목 설정 필요 여부

Node.js 실행 or Docker 지원	✅
이미지 최적화 (sharp)	✅
환경 변수 (NEXT_PUBLIC 포함)	✅
캐시 공유 핸들러	✅
CDN 설정 (ISR 지원)	✅
프록시 버퍼링 비활성화	✅
빌드 ID 동기화 (generateBuildId)	✅
종료 시그널 graceful 처리	✅

---

✨ 마무리

Next.js를 직접 호스팅하는 것은 더 많은 유연성을 주지만, 책임도 따릅니다. 캐싱 전략, 이미지 처리, CDN 최적화, 로그/모니터링까지 고려해야 할 것이 많지만, App Router는 이를 잘 다룰 수 있는 구조로 설계되어 있습니다.

---

 

Next.js, App Router, Self Hosting, Docker, Node.js 서버, 이미지 최적화, 환경변수 설정, 캐시 핸들링, CDN 구성, graceful shutdown, build ID 관리