Next.js 배포는 단순히 서버에 올리는 과정이 아니라
빌드, 최적화, 환경 분리, 실행까지 포함된 과정이다.
1. Vercel 배포
Next.js는 Vercel에서 가장 쉽게 배포할 수 있다.
배포 흐름
- GitHub에 코드 push
- Vercel에서 프로젝트 import
- 자동 빌드
- 배포 완료 (URL 생성)
특징
- Next.js와 높은 호환성
- SSR / SSG 자동 처리
- 서버리스 함수(
/api) 지원 - CDN 자동 적용
- Git 기반 CI/CD
추가 기능
- Preview 배포 (브랜치별)
- PR 미리보기 URL 생성
- 이전 배포로 롤백 가능
2. 빌드 과정 (next build)
npm run build빌드는 단순 번들링이 아니라
각 페이지의 렌더링 방식(SSR / SSG / ISR)을 결정하는 단계다.
빌드 시 수행 작업
- 코드 분할 (Code Splitting)
- 정적 페이지 생성 (SSG)
- 서버 코드 번들링 (SSR)
- 이미지 및 자산 최적화
- Tree Shaking
결과물
.next/- 정적 HTML
- JS 번들
- 서버 실행 코드
이 폴더가 없으면 production 실행 불가
3. 실행 (next start)
npm run start- production 환경에서 실행
- SSR 요청 처리
확인 방법
npm run build && npm run start배포 전에 반드시 실행해서
production 환경에서 문제 없는지 확인해야 한다.
4. 개발 vs 배포 환경 차이
개발 (next dev)
- Hot Reload
- 디버깅 중심
- 최적화 없음
배포 (build + start)
- 코드 최적화
- 캐싱 및 압축 적용
- 에러 기준 엄격
자주 발생하는 문제
- window / document 사용
- 환경 변수 누락
- hydration 불일치
예시
window.innerWidth→ 서버에서는 실행 불가
해결
if (typeof window !== "undefined") {
console.log(window.innerWidth);
}5. 환경 변수 (배포 시)
문제
.env.local은 로컬 전용이므로 배포 서버에 존재하지 않는다.
해결
Vercel에서 직접 설정
- Development
- Preview
- Production
예시
NEXT_PUBLIC_API_URL=https://api.myapp.com
JWT_SECRET=xxxx6. API 주소 문제
잘못된 방식
fetch("http://localhost:3000/api");배포 환경에서는 동작하지 않는다.
올바른 방식
fetch(`${process.env.NEXT_PUBLIC_API_URL}/api`);또는
fetch("/api");7. 빌드 에러 대응
자주 발생하는 문제
타입 에러
빌드 시 타입 오류 발생 → 타입 명확히 정의 필요
window is not defined
서버에서 실행되기 때문
hydration error
서버와 클라이언트 렌더링 결과 불일치
예시
const time = new Date();해결
useEffect(() => {
setTime(new Date());
}, []);8. 배포 체크리스트
npm run build성공npm run start로컬 테스트- 환경 변수 설정 완료
- API 주소 분리
- window 사용 여부 확인
9. 성능 최적화
next/image사용- dynamic import 적용
- CSR 최소화 (가능하면 SSR / SSG 사용)
10. 배포 흐름
git push → build → deploy → production정리
- 배포는 빌드 중심 과정이다.
- 개발과 배포 환경은 다르게 동작한다.
- 환경 변수는 별도로 관리해야 한다.
- 대부분의 문제는 환경 차이에서 발생한다.
한 줄 요약
Next.js 배포는 코드보다
환경 변수, 렌더링 전략(SSR/SSG), 실행 환경 차이에 더 크게 영향을 받는다.
⏰ Good things take time