🚢 Next.js 심화 10장: Deployment & Infrastructure — Vercel vs Docker vs Node.js 서버

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 세 가지 배포 전략 비교 🟢
• 🚀 Vercel 배포 — 제로 설정의 마법 🟡
• 🐳 Docker 컨테이너 배포 — 엔터프라이즈 표준 🟡
• 🖥️ Node.js 서버 직접 배포 🟡
• ⚙️ 환경 변수와 비밀키 관리 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 18분 (전체) / 핵심 파트만: 9분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영수(PM): "이제 서비스를 실제로 배포해야 해요. Vercel로 빠르게 나가야 하나요, 아니면 회사 서버(AWS EC2)에 Docker로 올려야 하나요? 차이가 뭔지 알고 결정하고 싶어요."
• 영호(리드): "팀 규모, 비용, 기술 성숙도에 따라 달라요. 스타트업 초기라면 Vercel이 최적이에요. ISR, Edge Functions, 프리뷰 배포가 기본이고 인프라 걱정을 아예 안 해도 되거든요. 반면 기업 내부 서버나 특정 규정(컴플라이언스)이 있으면 Docker로 자체 서버에 올려야 해요."

🗺️ 이 문서의 흐름
세 가지 전략 비교 → Vercel 배포 설정 → Docker 최적 Dockerfile → Node.js 서버 직접 배포 → 환경 변수 관리

🎯 이 문서를 다 읽으면 할 수 있는 것

• 팀과 서비스 상황에 맞는 배포 전략을 선택할 수 있다
• Next.js 앱을 위한 최적화된 Dockerfile을 작성할 수 있다
• 비밀키를 안전하게 관리하는 환경 변수 원칙을 지킬 수 있다

🤔 왜 알아야 하는가

로컬에서 잘 동작하던 코드가 배포 후 갑자기 안 동작하거나, 서버 비용이 예상보다 10배 나오거나, 환경 변수가 클라이언트에 노출되는 사고 — 배포를 모르면 이런 일이 생겨.

배포는 "어떤 인프라에서 어떻게 실행할 것인가"에 대한 아키텍처 결정이야. 코딩만큼 중요한 선택이야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?
음식 배달 방식에 비유해봐:

• Vercel = 배달의민족 입점. 주방만 있으면 되고, 배달·결제·광고는 플랫폼이 다 해줘. 빠른 대신 수수료(비용)가 있고, 플랫폼 규칙을 따라야 해.
• Docker = 음식점 직접 운영 + 배달 트럭 보유. 모든 걸 직접 관리해야 하지만 자유도가 최고야.
• Node.js 직접 배포 = 음식점 직접 운영인데 배달 트럭은 세놓기. Docker보다 조금 더 단순하지만 관리할 게 여전히 많아.

🧩 세 가지 배포 전략 비교 🟢

🎯 이 섹션을 읽고 나면:

• 세 가지 배포 전략의 장단점을 정확히 알고 상황에 맞는 선택을 할 수 있다

2026년 기준 선택 가이드:

팀 규모 소 + 빠른 출시 + 비용 최소화 → Vercel
데이터 국내 서버 필수 + 기업 보안 규정 → Docker (사내 K8s)
기존 VM 보유 + 단순 배포 + 예측 비용 → Node.js 직접 배포

🚀 Vercel 배포 — 제로 설정의 마법 🟡

🎯 이 섹션을 읽고 나면:

• Vercel에서 환경 변수를 설정하고 커스텀 도메인을 연결할 수 있다
• vercel.json으로 리다이렉트와 헤더를 설정할 수 있다

Vercel 배포 과정:

# 1. Vercel CLI 설치
npm i -g vercel
 
# 2. 프로젝트 연결 및 배포
vercel
 
# 3. 프로덕션 배포
vercel --prod

또는 GitHub 연동으로 push할 때마다 자동 배포 (권장).

vercel.json 설정:

{
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "devCommand": "npm run dev",
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "Strict-Transport-Security", "value": "max-age=31536000; includeSubDomains" }
      ]
    }
  ],
  "redirects": [
    { "source": "/old-blog/(.*)", "destination": "/posts/$1", "permanent": true }
  ]
}

Vercel 환경 변수 설정:

Vercel Dashboard → 프로젝트 → Settings → Environment Variables

개발: DATABASE_URL=postgresql://localhost:5432/dev
프리뷰: DATABASE_URL=postgresql://preview-server/preview
프로덕션: DATABASE_URL=postgresql://prod-server/prod

⚠️ NEXT_PUBLIC_ 접두사가 붙은 변수만 클라이언트에 노출됨!

Vercel의 특별 기능:

✅ Preview URL: PR마다 고유한 미리보기 URL 자동 생성
   - https://my-app-pr-123-team.vercel.app

✅ ISR 지원: revalidate 설정 즉시 동작
✅ Edge Functions: middleware가 Vercel Edge에서 자동 실행
✅ Analytics: Core Web Vitals 실제 사용자 데이터 자동 수집

🐳 Docker 컨테이너 배포 — 엔터프라이즈 표준 🟡

🎯 이 섹션을 읽고 나면:

• Next.js 앱을 위한 최적화된 멀티 스테이지 Dockerfile을 작성할 수 있다
• 이미지 크기를 최소화하는 빌드 패턴을 적용할 수 있다

Next.js 공식 권장 멀티 스테이지 Dockerfile:

# Dockerfile
 
# ─────────────────────────────────────────
# Stage 1: 의존성 설치
# ─────────────────────────────────────────
FROM node:20-alpine AS deps
WORKDIR /app
 
# package.json과 lock 파일만 먼저 복사 (레이어 캐싱 최적화)
COPY package.json package-lock.json ./
RUN npm ci --only=production
 
# ─────────────────────────────────────────
# Stage 2: 빌드
# ─────────────────────────────────────────
FROM node:20-alpine AS builder
WORKDIR /app
 
# 빌드에 필요한 전체 의존성 설치 (devDependencies 포함)
COPY package.json package-lock.json ./
RUN npm ci
 
COPY . .
 
# 빌드 타임 환경 변수
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
 
# standalone 모드로 빌드 (서버에 필요한 파일만 출력)
RUN npm run build
 
# ─────────────────────────────────────────
# Stage 3: 실행 이미지 (최소 크기)
# ─────────────────────────────────────────
FROM node:20-alpine AS runner
WORKDIR /app
 
ENV NODE_ENV=production
 
# 보안: 루트 권한으로 실행하지 않기
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# standalone 빌드 결과물만 복사 (최소 파일)
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
CMD ["node", "server.js"]

// next.config.ts — standalone 모드 활성화 (Docker 필수 설정)
const nextConfig = {
  output: 'standalone',    // 서버에 필요한 최소 파일만 .next/standalone에 출력
}

# docker-compose.yml — 로컬 개발/스테이징용
services:
  app:
    build:
      context: .
      args:
        NEXT_PUBLIC_API_URL: https://api.youngsu.community
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/youngsu
      - SESSION_SECRET=your-secret-key-here
    depends_on:
      - db
 
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: youngsu
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
 
volumes:
  postgres_data:

# 이미지 빌드 및 실행
docker build -t youngsu-community .
docker run -p 3000:3000 --env-file .env.production youngsu-community
 
# 또는 compose로
docker-compose up -d

🖥️ Node.js 서버 직접 배포 🟡

기존 EC2, NCP 같은 VM에 직접 배포하는 방법이야.

# server.sh — 서버 배포 스크립트
#!/bin/bash
set -e
 
echo "📦 의존성 설치..."
npm ci
 
echo "🔨 빌드..."
npm run build
 
echo "🔄 서버 재시작 (PM2 사용)..."
pm2 restart youngsu-community || pm2 start npm --name youngsu-community -- start
 
echo "✅ 배포 완료!"

// ecosystem.config.js — PM2 설정
module.exports = {
  apps: [
    {
      name: 'youngsu-community',
      script: 'npm',
      args: 'start',
      instances: 'max',    // CPU 코어 수만큼 프로세스 실행
      exec_mode: 'cluster',
      env: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
    },
  ],
}

⚙️ 환경 변수와 비밀키 관리 🔴

🎯 이 섹션을 읽고 나면:

• NEXT_PUBLIC_ 접두사의 의미와 위험성을 이해한다
• 비밀키가 클라이언트 번들에 포함되는 사고를 방지하는 규칙을 안다

🤔 잠깐, 먼저 생각해봐
NEXT_PUBLIC_DATABASE_URL=postgresql://...이라고 환경 변수를 설정하면 어떤 일이 생길까?

환경 변수의 두 종류:

NEXT_PUBLIC_ 접두사 있음 → 클라이언트(브라우저) 번들에 포함
                           → 누구나 DevTools에서 볼 수 있음 ⚠️

NEXT_PUBLIC_ 접두사 없음 → 서버에서만 접근 가능
                           → 브라우저에 절대 노출 안 됨 ✅

# .env.local (로컬 전용 — .gitignore에 반드시 포함!)
DATABASE_URL=postgresql://localhost:5432/dev     # 서버 전용 ✅
SESSION_SECRET=dev-secret-key                    # 서버 전용 ✅
NEXT_PUBLIC_API_URL=http://localhost:3000         # 클라이언트 접근 가능 (공개 OK)
 
# ❌ 절대 금지!
NEXT_PUBLIC_DATABASE_URL=postgresql://...        # DB 접속 정보가 브라우저에 노출!
NEXT_PUBLIC_SESSION_SECRET=secret-key            # 암호화 키가 브라우저에 노출!

server-only 패키지로 실수 방지:

// lib/db.ts — 서버에서만 실행되는 파일
import 'server-only'
import { PrismaClient } from '@prisma/client'
 
// 이 파일이 클라이언트 컴포넌트에서 import되면 빌드 에러 발생
// → 실수로 DB 연결 정보가 클라이언트에 노출되는 사고 방지
export const db = new PrismaClient()

.env 파일 계층:

.env              → 기본값 (git 추적 가능, 민감 정보 없어야 함)
.env.local        → 로컬 개발 (git 제외, 개인 설정)
.env.development  → 개발 환경 (git 추적 가능)
.env.production   → 프로덕션 (git 제외! 또는 비밀 관리 서비스로)

💥 에러 해결 카탈로그

❌ Docker 빌드 후 output: 'standalone' 결과물에 public 파일 없음

원인: standalone 모드는 public 폴더를 자동으로 포함하지 않아.

해결책:

# Dockerfile에서 public 폴더를 명시적으로 복사
COPY --from=builder /app/public ./public

❌ 배포 후 환경 변수를 못 읽음 (undefined)

원인 체크리스트:

1. .env.local은 로컬 전용. 서버에서는 시스템 환경 변수 또는 .env.production 사용
2. NEXT_PUBLIC_ 없는 변수를 클라이언트 코드에서 읽으려 한 경우
3. Docker 실행 시 --env-file 옵션 누락

❌ Vercel 배포 후 API Route가 504 Timeout

원인: Vercel의 무료 플랜에서 함수 실행 시간 한도(10초) 초과.

해결책:

// vercel.json에서 특정 경로 타임아웃 연장 (Pro 플랜 필요)
{
  "functions": {
    "app/api/heavy-task/route.ts": {
      "maxDuration": 60
    }
  }
}

🏁 이번에 배운 내용 총정리

📋 배포 전략 선택 기준

⚠️ 절대 하지 말 것

📝 마무리 퀴즈

Q1. NEXT_PUBLIC_SESSION_SECRET처럼 비밀키에 NEXT_PUBLIC_ 접두사를 붙이면 어떤 문제가 생기는가?

✅ 정답: 값이 클라이언트 번들에 포함되어 브라우저에서 노출된다.

💡 상세 해설: NEXT_PUBLIC_은 "브라우저에서 읽어도 되는 값"이라는 선언이다. 세션 서명키, DB URL, API secret에는 절대 붙이면 안 된다. 환경 변수 이름은 배포 전략보다 먼저 확인해야 하는 보안 경계다.

Q2. Docker 배포에서 output: 'standalone'을 사용할 때 public 폴더와 .next/static을 별도로 복사해야 하는 이유는?

✅ 정답: standalone 출력은 실행 서버에 필요한 최소 파일 중심이라 정적 자산을 자동으로 모두 포함하지 않기 때문이다.

💡 상세 해설: standalone은 이미지 크기를 줄이는 데 유용하지만, Dockerfile에서 public과 .next/static을 명시적으로 복사하지 않으면 이미지, 폰트, JS 정적 파일이 404가 될 수 있다. 빌드 성공과 런타임 정적 자산 제공은 별개의 검증이다.

Q3. 영철이의 테스트 타임: 자체 Node 서버를 여러 인스턴스로 띄렸더니 ISR/태그 캐시 반영 시점이 인스턴스마다 다르다. 무엇을 검토해야 할까?

✅ 정답: 공유 캐시, 태그 무효화 전파, CDN 캐시 정책처럼 다중 인스턴스에서 캐시 일관성을 맞추는 인프라를 검토해야 한다.

💡 상세 해설: 공식 배포 문서도 기본 Node 서버는 기능을 수행하지만, 다중 인스턴스에서는 공유 캐시와 무효화 조율이 운영 품질을 좌우한다고 설명한다. Vercel은 많은 부분을 플랫폼이 맡지만, 자체 배포는 팀이 직접 관측과 전파 경로를 설계해야 한다.

🐣 영철이의 퇴근 일기

오늘은 배포를 "서버에 올리기"가 아니라 Next.js 런타임 기능이 실제 환경에서 끝까지 작동하게 만드는 일로 보게 됐다. Server Components, streaming, ISR, Server Actions, 정적 자산이 모두 배포 플랫폼의 지원과 연결되어 있었다.

💡 "배포 전략은 비용표가 아니라 런타임 기능 요구사항의 결과다."

다음 배포 설계에서는 Vercel, Docker, 자체 Node 서버를 취향으로 고르지 않겠다. 스트리밍이 필요한지, 서버 액션 본문 제한은 충분한지, 이미지 최적화와 공유 캐시는 누가 책임지는지부터 확인하고 선택지를 제안하겠다.

🔗 더 알아보기

• Next.js 공식 문서 — Deployment
• Next.js Docker 공식 예제
• PM2 공식 문서
• Vercel 환경 변수 가이드