🚀 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=abc123 으로 설정했을 때 발생하는 문제는?

• A) 서버에서 환경 변수를 읽지 못한다
• B) 브라우저 DevTools에서 이 값을 누구나 볼 수 있다
• C) Next.js 빌드가 실패한다
• D) 쿠키가 자동으로 초기화된다

✅ 정답: B

해설: NEXT_PUBLIC_ 접두사는 클라이언트 번들에 값을 포함시켜. 브라우저 개발자 도구에서 누구나 확인 가능해. 세션 비밀키가 노출되면 모든 JWT를 위조할 수 있어.

📌 핵심 기억법: NEXT_PUBLIC_ = "공개 방송". 비밀키엔 절대 붙이지 마.

Q2. Docker output: 'standalone'의 장점으로 옳지 않은 것은?

• A) 불필요한 node_modules를 포함하지 않아 이미지 크기가 작아진다
• B) 실행에 필요한 최소 파일만 포함된다
• C) public 폴더가 자동으로 포함된다
• D) 멀티 스테이지 빌드와 함께 쓰면 이미지 크기를 크게 줄일 수 있다

✅ 정답: C

해설: standalone 모드는 public 폴더를 자동으로 포함하지 않아. Dockerfile에서 명시적으로 COPY --from=builder /app/public ./public을 해줘야 해.

📌 핵심 기억법: standalone은 standalone이야. public은 별도로 챙겨야 해.

Q3. 친구에게 설명한다면?

스타트업 초기에 Vercel을 선택하고, 나중에 Docker로 마이그레이션하는 이유를 설명해봐.

예시 답변:

"Vercel은 배달의민족 입점이야. 처음엔 빠르고 편해. 근데 트래픽이 늘면 수수료(비용)가 기하급수적으로 늘어. 그리고 '우리 서버에 저장해야 한다'는 기업 규정이 생기면 Vercel은 미국 서버라 불가능해. 그때 Docker로 자체 서버에 옮기는 거야. 초기엔 속도, 나중엔 제어권이 더 중요해지는 성장 단계에 따른 전략 변화야."

🐣 영철이의 퇴근 일기

오늘은 정말 넥스트 앱이 세상으로 나가는 관문인 'Deployment & Infra' 를 배우면서 가슴이 벅차올랐어! 단순히 코드를 짜는 걸 넘어, Docker의 멀티 스테이지 빌드로 이미지를 깎고 Vercel과 자체 서버 사이의 전략을 고민하는 과정이 정말 흥미로웠어.

💡 오늘의 교훈: "배포는 끝이 아니라 새로운 시작이다. Vercel로 빠르게 출시하고, 성장 단계에 맞춰 Docker와 자체 서버로 확장하며 전 세계 유저에게 안정적인 서비스를 제공하자!"

영호 리드 님이 배달 앱 비유를 들어 설명해 주실 때, 왜 상황에 맞는 배포 전략이 중요한지 단번에 이해가 가더라. 특히 환경 변수 하나에 서비스의 운명이 갈릴 수 있다는 말씀에 정신이 번쩍 들었어. 오늘 너무 긴장하면서 서버 설정을 만졌더니 배가 출출하네. 퇴근길에 내가 좋아하는 '배달 음식' 하나 시켜서 맛있게 먹으면서 오늘 배운 배포 로직을 복습해야겠어. 내일은 더 '안정적인' 서비스를 운영하는 개발자가 될 거야! 🐣

🔗 더 알아보기

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