콘텐츠로 이동

Next.js Runtime Short Runbook

이 문서를 볼 때

  • Next.js 서비스를 운영 서버에 배포할 때
  • Next.js와 Node.js API 서버의 운영 차이를 판단할 때
  • PM2, standalone, image optimization, caching, env를 점검할 때

먼저 필요한 입력값

  • Next.js 버전과 router 방식
  • output mode: standalone 사용 여부
  • SSR/SSG/ISR 사용 여부
  • 이미지 최적화 사용 여부
  • runtime env와 NEXT_PUBLIC_* 값
  • listen host/port
  • PM2 process name
  • Nginx route/cache 정책

작업 순서

  1. Next.js를 gateway/backend로 쓰려는지 먼저 차단
  2. Node.js 설치 기준 확인
  3. 빌드 산출물 구조와 실행 방식 결정
  4. env 공개/비공개 경계 확인
  5. PM2 ecosystem config 구성
  6. startup/systemd 연동
  7. Nginx reverse proxy와 /_next/ cache 정책 확인
  8. image optimization 의존성 확인
  9. 로그/에러 처리 기준 확인
  10. Do Not Do List 위반 여부 확인

중단 조건

  • next dev를 운영에서 실행하려 함
  • build 없이 next start를 실행하려 함
  • NEXT_PUBLIC_*에 secret을 넣으려 함
  • Next.js 포트를 외부에 직접 노출하려 함
  • Next.js를 reverse proxy/gateway처럼 쓰려 함
  • PM2 cluster에 대한 기대가 Next.js 동작과 맞지 않음

검증 명령

node -v
npm -v
npx next --version
ls -la .next
pm2 status
pm2 describe <process-name>
nginx -t
curl -I https://example.com
curl -I https://example.com/_next/static/

상세 문서