[유데미 러닝크루] Next.js 스터디 5주차 - Next.js 배포 실전 마스터 가이드 (표준 빌드, 정적 배포, Vercel 실습까지)

📑 목차

• 1) 5주차 진행 범위 & Udemy 강의 소개
• 2) 5주차 학습 정리 — Next.js 배포 과정
• — 1️⃣ next build vs next export
• — 2️⃣ 빌드 결과 읽기 & 재배포 필요성
• — 3️⃣ fallback 개념
• — 4️⃣ next.config.js 핵심
• — 5️⃣ 환경변수 & 단계별 분기
• — 6️⃣ 번들 최적화(하이라이터)
• — 7️⃣ 로컬 프로덕션 테스트
• — 8️⃣ GitHub × Vercel 배포
• — 9️⃣ MongoDB 연결 오류 해결
• — 🔟 수정 후 자동 재배포
• 🔥 최종 정리

1. 5주차 진행 범위

📝 세션 18 ~ 23 강의까지 진행

［Udemy 강의 소개］

이번 스터디에서 수강하는 강의는 【한글자막】 Next.js 15 & React - 완벽 가이드이다. 이 강의에서는 Next.js 15를 기초부터 학습하고, 앱 라우터 & 페이지 라우터를 활용하여 풀스택 앱을 구축하는 방법을 배울 수 있다.

💡 강의 정보

• 강의명: 【한글자막】 Next.js 15 & React - 완벽 가이드
• 강의 시간: 40시간
• 수강생: 5,021명
• 강의 평가: ⭐ 4.7/5 (585명 평가)
• 언어: 한국어 자막 제공

📌 강의 주요 내용

✅ Next.js 15의 앱 라우터 & 페이지 라우터 ✅ 서버/클라이언트 컴포넌트 이해 ✅ 서버 액션 기반 데이터 처리 ✅ SSR·파일 기반 라우팅·인증 기능

2. 5주차 학습 내용 정리 — Next.js 배포 과정

표준 빌드/정적 빌드 차이, Vercel 자동 배포, 성능 최적화와 환경 설정까지 실전 위주로 정리.

1️⃣ Next.js 배포 방식 — next build vs next export

✔ Standard Build (next build)

• 가장 일반적인 방식, 서버 기능 사용 가능 (API Routes, getServerSideProps, ISR 등)
• 빌드 산출물은 .next/에 저장, Node.js 서버가 필요
• 요청마다 서버에서 페이지 생성/검증 가능 → 로그인 후 유저 조회, 최신 데이터 서비스에 적합

✔ Static Export (next export)

• 100% 정적 HTML/CSS/JS 생성 → 서버 없이 호스팅(GitHub Pages/Netlify 등)
• 사용 불가: getServerSideProps, API Route, ISR, fallback 등
• 콘텐츠 변경 시 다시 export 필요 → 블로그/포트폴리오에 적합

2️⃣ 빌드 결과 읽기 & 재배포 필요성

• 터미널 표시:
  • ○ 완전 정적 페이지
  • ● 서버에서 처리
  • λ SSR 필요 페이지
• ISR 미사용 시 콘텐츠 수정 때마다 재빌드/재배포 필수

3️⃣ fallback 옵션 개념

• getStaticPaths + fallback: true | blocking ⇒ 빌드 때 생성 안 한 경로도 요청 시 서버에서 즉시 생성
• 서버 러닝이 필요하므로 next export에서는 불가

4️⃣ next.config.js 핵심

• basePath (서브 경로 배포), redirects/rewrites (라우팅 제어)
• headers (응답 헤더), env (환경변수), webpack 확장
• 이번 프로젝트에선 환경변수 설정이 주 사용처

5️⃣ 환경변수 & 개발/배포 분기

기본 환경변수

env: {
  mongodb_username: "your_user",
  mongodb_password: "your_pass",
  mongodb_clustername: "cluster0",
  mongodb_database: "my-site-dev"
}

단계별 분기 — 개발/배포에 따라 다른 값을 노출

const { PHASE_DEVELOPMENT_SERVER } = require("next/constants");

module.exports = (phase) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      env: { mongodb_database: "my-site-dev" }
    };
  }
  return {
    env: { mongodb_database: "my-site" }
  };
};

→ 개발에선 테스트 DB, 배포에선 운영 DB로 안전하게 분리.

6️⃣ 성능 최적화 — 구문 하이라이터 번들 사이즈 줄이기

문제: 게시물 상세 번들이 320kB로 과도하게 큼 (모든 언어 지원 포함)

해결 — 라이트 버전 + 필요한 언어만 등록

import { PrismLight as SyntaxHighlighter } from "react-syntax-highlighter";
import js from "react-syntax-highlighter/dist/cjs/languages/prism/javascript";
SyntaxHighlighter.registerLanguage("js", js);

결과 — 320kB → 114kB로 최적화

7️⃣ 로컬에서 프로덕션 테스트

npm run build   # 프로덕션 빌드
npm start       # 프로덕션 서버 (http://localhost:3000)

• 정적 페이지/데이터가 의도대로 생성되는지 확인
• 배포 환경과 동일 동작인지 점검

8️⃣ GitHub × Vercel 배포

GitHub

• git init → git add . → git commit
• 원격 저장소 생성 후 git push (토큰 인증)

Vercel

• GitHub 연동 → 저장소 선택 시 Next.js 자동 인식
• 환경변수 등록
• push만 해도 자동 재배포

9️⃣ MongoDB 연결 오류 해결

원인 — Atlas 기본 설정이 외부 IP 차단 상태

해결

• Atlas > Network Access에서 0.0.0.0/0 허용(또는 배포 IP/범위 추가)
• 환경변수만 맞춰도 IP 허용이 없으면 연결 실패

🔟 배포 후 코드 수정 & 자동 재배포

1. 코드 수정 → git commit → git push
2. Vercel이 변경 감지 → 자동 재배포
3. 기존 URL에 최신 버전 반영

🔥 최종 정리

• ✅ next build: 서버 기능 사용, Node.js 필요
• ✅ next export: 정적 사이트 전용, 서버 기능 불가
• ✅ fallback/SSR/API/ISR은 항상 서버 필요
• ✅ 환경변수 분기로 개발/운영 안전 분리
• ✅ 구문 하이라이터 라이트+선택 등록으로 번들 축소
• ✅ GitHub × Vercel로 자동 배포 파이프라인 구축
• ✅ MongoDB Atlas는 IP 허용이 핵심 포인트