Next.js 학습 자료

Next.js 프레임워크 학습을 위한 30장의 마크다운 자료입니다.

← 목록으로

챕터 29: 배포 준비하기

서론

드디어 여러분의 웹사이트를 전 세계에 공개할 때가 왔습니다! 하지만 잠깐, 배포 버튼을 누르기 전에 확인해야 할 것들이 있습니다. 개발 환경에서는 잘 동작하던 애플리케이션이 프로덕션 환경에서는 예상치 못한 문제를 일으킬 수 있습니다. 성능 문제, 보안 취약점, 환경 설정 오류 등 다양한 함정이 숨어있을 수 있습니다.

이번 챕터에서는 안전하고 성공적인 배포를 위한 모든 준비 과정을 다룹니다. 프로덕션 빌드의 이해, 환경 변수 설정, 성능 최적화, 그리고 배포 전 반드시 확인해야 할 체크리스트까지 상세히 알아보겠습니다. 이 과정을 통해 여러분의 웹사이트는 실제 사용자들을 맞이할 준비를 완벽하게 마치게 될 것입니다.

본론

프로덕션 빌드 이해하기

개발 모드와 프로덕션 모드의 차이를 이해하는 것은 매우 중요합니다:

// package.json
{
  "scripts": {
    "dev": "next dev",        // 개발 모드 - 핫 리로딩, 디버깅 도구 활성화
    "build": "next build",    // 프로덕션 빌드 생성
    "start": "next start",    // 프로덕션 서버 실행
    "lint": "next lint"       // 코드 품질 검사
  }
}

프로덕션 빌드를 생성해봅시다:

npm run build

빌드 과정에서 Next.js는 다음과 같은 최적화를 수행합니다:

  • JavaScript 번들 최소화
  • 이미지 최적화
  • 폰트 최적화
  • 정적 페이지 사전 렌더링
  • 코드 스플리팅

빌드가 완료되면 상세한 분석 결과를 볼 수 있습니다:

// app/build-info/page.js
export default function BuildInfoPage() {
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <div className="max-w-4xl mx-auto">
        <h1 className="text-3xl font-bold mb-8">빌드 최적화 가이드</h1>
        
        <div className="bg-white rounded-lg shadow-md p-6 mb-6">
          <h2 className="text-xl font-semibold mb-4">📊 빌드 출력 이해하기</h2>
          
          <div className="space-y-4">
            <div className="border-l-4 border-green-500 pl-4">
              <p className="font-semibold">○ (정적)</p>
              <p className="text-gray-600">빌드 시 자동으로 정적 HTML로 렌더링됨</p>
            </div>
            
            <div className="border-l-4 border-blue-500 pl-4">
              <p className="font-semibold">λ (서버)</p>
              <p className="text-gray-600">서버 사이드 렌더링 함수</p>
            </div>
            
            <div className="border-l-4 border-purple-500 pl-4">
              <p className="font-semibold">● (ISR)</p>
              <p className="text-gray-600">Incremental Static Regeneration 사용</p>
            </div>
          </div>
        </div>
        
        <div className="bg-white rounded-lg shadow-md p-6">
          <h2 className="text-xl font-semibold mb-4">🎯 번들 크기 최적화</h2>
          
          <pre className="bg-gray-900 text-white p-4 rounded overflow-x-auto">
            <code>{`// next.config.js
module.exports = {
  // 번들 분석기 활성화
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.optimization.splitChunks = {
        chunks: 'all',
        cacheGroups: {
          default: false,
          vendors: false,
          vendor: {
            name: 'vendor',
            chunks: 'all',
            test: /node_modules/
          }
        }
      }
    }
    return config
  },
  
  // 이미지 최적화
  images: {
    domains: ['example.com'],
    formats: ['image/avif', 'image/webp']
  },
  
  // 압축 활성화
  compress: true,
  
  // 소스맵 비활성화 (프로덕션)
  productionBrowserSourceMaps: false
}`}</code>
          </pre>
        </div>
      </div>
    </div>
  )
}

환경 변수 설정하기

환경 변수는 개발, 스테이징, 프로덕션 환경에서 다른 설정을 사용할 수 있게 해줍니다:

// app/env-guide/page.js
export default function EnvGuidePage() {
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <div className="max-w-4xl mx-auto">
        <h1 className="text-3xl font-bold mb-8">환경 변수 완벽 가이드</h1>
        
        <div className="bg-white rounded-lg shadow-md p-6 mb-6">
          <h2 className="text-xl font-semibold mb-4">📁 환경 변수 파일 구조</h2>
          
          <div className="bg-gray-100 rounded p-4 font-mono text-sm">
            <div className="mb-2">
              <span className="text-green-600">.env.local</span>
              <span className="text-gray-600"> # 로컬 개발 환경 (Git 무시)</span>
            </div>
            <div className="mb-2">
              <span className="text-blue-600">.env.development</span>
              <span className="text-gray-600"> # 개발 환경</span>
            </div>
            <div className="mb-2">
              <span className="text-purple-600">.env.production</span>
              <span className="text-gray-600"> # 프로덕션 환경</span>
            </div>
            <div>
              <span className="text-red-600">.env</span>
              <span className="text-gray-600"> # 모든 환경 (기본값)</span>
            </div>
          </div>
        </div>
        
        <div className="bg-white rounded-lg shadow-md p-6 mb-6">
          <h2 className="text-xl font-semibold mb-4">🔐 환경 변수 예제</h2>
          
          <pre className="bg-gray-900 text-white p-4 rounded overflow-x-auto mb-4">
            <code>{`# .env.local
# 데이터베이스 설정
DATABASE_URL=postgresql://localhost:5432/myapp_dev
DATABASE_PASSWORD=dev_password

# API 키 (절대 Git에 커밋하지 마세요!)
STRIPE_SECRET_KEY=sk_test_...
GOOGLE_ANALYTICS_ID=UA-000000-1

# 공개 환경 변수 (브라우저에서 접근 가능)
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_SITE_NAME=My Dev Site`}</code>
          </pre>
          
          <pre className="bg-gray-900 text-white p-4 rounded overflow-x-auto">
            <code>{`# .env.production
# 프로덕션 데이터베이스
DATABASE_URL=postgresql://prod-server:5432/myapp
DATABASE_PASSWORD=\${PROD_DB_PASSWORD}

# 프로덕션 API 키
STRIPE_SECRET_KEY=sk_live_...
GOOGLE_ANALYTICS_ID=UA-123456-1

# 공개 프로덕션 설정
NEXT_PUBLIC_API_URL=https://api.mysite.com
NEXT_PUBLIC_SITE_NAME=My Production Site`}</code>
          </pre>
        </div>
        
        <div className="bg-yellow-50 border border-yellow-400 rounded-lg p-6">
          <h3 className="text-lg font-semibold text-yellow-800 mb-2">
            ⚠️ 중요한 보안 규칙
          </h3>
          <ul className="space-y-2 text-gray-700">
            <li>• NEXT_PUBLIC_ 접두사가 있는 변수만 클라이언트에서 접근 가능합니다</li>
            <li>• 민감한 정보는 절대 NEXT_PUBLIC_ 접두사를 사용하지 마세요</li>
            <li>• .env.local 파일은 반드시 .gitignore에 추가하세요</li>
            <li>• 프로덕션 환경 변수는 호스팅 서비스에서 직접 설정하세요</li>
          </ul>
        </div>
      </div>
    </div>
  )
}

성능 최적화 체크리스트

// app/optimization/page.js
'use client'

import { useState } from 'react'

export default function OptimizationChecklist() {
  const [checkedItems, setCheckedItems] = useState({})
  
  const optimizations = [
    {
      category: '이미지 최적화',
      items: [
        { id: 'img1', text: 'Next.js Image 컴포넌트 사용', priority: 'high' },
        { id: 'img2', text: '적절한 이미지 포맷 선택 (WebP, AVIF)', priority: 'high' },
        { id: 'img3', text: 'lazy loading 적용', priority: 'medium' },
        { id: 'img4', text: '반응형 이미지 구현', priority: 'medium' },
        { id: 'img5', text: 'placeholder blur 사용', priority: 'low' }
      ]
    },
    {
      category: '코드 최적화',
      items: [
        { id: 'code1', text: '사용하지 않는 의존성 제거', priority: 'high' },
        { id: 'code2', text: '동적 import로 코드 스플리팅', priority: 'high' },
        { id: 'code3', text: 'tree shaking 확인', priority: 'medium' },
        { id: 'code4', text: 'console.log 제거', priority: 'medium' },
        { id: 'code5', text: 'React.memo 적절히 사용', priority: 'low' }
      ]
    },
    {
      category: '폰트 최적화',
      items: [
        { id: 'font1', text: 'next/font 사용하여 폰트 최적화', priority: 'high' },
        { id: 'font2', text: 'font-display: swap 적용', priority: 'medium' },
        { id: 'font3', text: '필요한 문자셋만 로드', priority: 'low' }
      ]
    },
    {
      category: 'SEO 최적화',
      items: [
        { id: 'seo1', text: '메타 태그 설정', priority: 'high' },
        { id: 'seo2', text: 'Open Graph 태그 추가', priority: 'high' },
        { id: 'seo3', text: 'sitemap.xml 생성', priority: 'medium' },
        { id: 'seo4', text: 'robots.txt 설정', priority: 'medium' },
        { id: 'seo5', text: '구조화된 데이터 추가', priority: 'low' }
      ]
    },
    {
      category: '성능 측정',
      items: [
        { id: 'perf1', text: 'Lighthouse 점수 90+ 달성', priority: 'high' },
        { id: 'perf2', text: 'Core Web Vitals 측정', priority: 'high' },
        { id: 'perf3', text: '번들 크기 분석', priority: 'medium' },
        { id: 'perf4', text: '실제 기기에서 테스트', priority: 'medium' }
      ]
    }
  ]
  
  const toggleCheck = (id) => {
    setCheckedItems(prev => ({
      ...prev,
      [id]: !prev[id]
    }))
  }
  
  const getPriorityColor = (priority) => {
    switch(priority) {
      case 'high': return 'text-red-600 bg-red-50'
      case 'medium': return 'text-yellow-600 bg-yellow-50'
      case 'low': return 'text-green-600 bg-green-50'
      default: return 'text-gray-600 bg-gray-50'
    }
  }
  
  const completedCount = Object.values(checkedItems).filter(Boolean).length
  const totalCount = optimizations.reduce((acc, cat) => acc + cat.items.length, 0)
  const progress = (completedCount / totalCount) * 100
  
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <div className="max-w-4xl mx-auto">
        <h1 className="text-3xl font-bold mb-8">🚀 배포 전 최적화 체크리스트</h1>
        
        {/* 진행률 표시 */}
        <div className="bg-white rounded-lg shadow-md p-6 mb-8">
          <div className="flex justify-between mb-2">
            <span className="text-gray-600">전체 진행률</span>
            <span className="font-semibold">{completedCount}/{totalCount} 완료</span>
          </div>
          <div className="w-full bg-gray-200 rounded-full h-3">
            <div 
              className="bg-gradient-to-r from-blue-500 to-green-500 h-3 rounded-full transition-all duration-300"
              style={{ width: `${progress}%` }}
            />
          </div>
        </div>
        
        {/* 체크리스트 */}
        {optimizations.map(category => (
          <div key={category.category} className="bg-white rounded-lg shadow-md p-6 mb-6">
            <h2 className="text-xl font-semibold mb-4">{category.category}</h2>
            
            <div className="space-y-3">
              {category.items.map(item => (
                <label 
                  key={item.id}
                  className="flex items-center cursor-pointer hover:bg-gray-50 p-2 rounded"
                >
                  <input
                    type="checkbox"
                    checked={checkedItems[item.id] || false}
                    onChange={() => toggleCheck(item.id)}
                    className="w-5 h-5 text-blue-600 rounded focus:ring-blue-500"
                  />
                  <span className={`ml-3 flex-1 ${checkedItems[item.id] ? 'line-through text-gray-400' : ''}`}>
                    {item.text}
                  </span>
                  <span className={`px-2 py-1 rounded text-xs font-semibold ${getPriorityColor(item.priority)}`}>
                    {item.priority === 'high' ? '필수' : item.priority === 'medium' ? '권장' : '선택'}
                  </span>
                </label>
              ))}
            </div>
          </div>
        ))}
        
        {/* 추가 팁 */}
        <div className="bg-blue-50 border border-blue-200 rounded-lg p-6">
          <h2 className="text-xl font-semibold text-blue-800 mb-4">💡 프로 팁</h2>
          <ul className="space-y-2 text-gray-700">
            <li>• 배포 전에 반드시 로컬에서 프로덕션 빌드를 테스트하세요: <code className="bg-white px-2 py-1 rounded">npm run build && npm run start</code></li>
            <li>• 환경 변수가 올바르게 설정되었는지 확인하세요</li>
            <li>• 에러 페이지(404, 500)를 커스터마이징하세요</li>
            <li>• 분석 도구(Google Analytics, Vercel Analytics)를 설정하세요</li>
            <li>• 배포 후 실제 도메인에서 모든 기능을 테스트하세요</li>
          </ul>
        </div>
      </div>
    </div>
  )
}

보안 체크리스트

// app/security/page.js
export default function SecurityChecklist() {
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <div className="max-w-4xl mx-auto">
        <h1 className="text-3xl font-bold mb-8">🔒 보안 체크리스트</h1>
        
        <div className="bg-red-50 border border-red-200 rounded-lg p-6 mb-8">
          <h2 className="text-xl font-semibold text-red-800 mb-4">🚨 필수 보안 설정</h2>
          
          <div className="space-y-4">
            <div className="bg-white rounded p-4">
              <h3 className="font-semibold mb-2">1. 환경 변수 보호</h3>
              <pre className="bg-gray-900 text-white p-3 rounded text-sm overflow-x-auto">
                <code>{`// ❌ 잘못된 예
const apiKey = "sk_live_abcd1234"

// ✅ 올바른 예
const apiKey = process.env.API_SECRET_KEY`}</code>
              </pre>
            </div>
            
            <div className="bg-white rounded p-4">
              <h3 className="font-semibold mb-2">2. CORS 설정</h3>
              <pre className="bg-gray-900 text-white p-3 rounded text-sm overflow-x-auto">
                <code>{`// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/:path*',
        headers: [
          { key: 'Access-Control-Allow-Origin', value: 'https://yourdomain.com' },
          { key: 'Access-Control-Allow-Methods', value: 'GET,POST,PUT,DELETE' },
        ],
      },
    ]
  },
}`}</code>
              </pre>
            </div>
            
            <div className="bg-white rounded p-4">
              <h3 className="font-semibold mb-2">3. 콘텐츠 보안 정책 (CSP)</h3>
              <pre className="bg-gray-900 text-white p-3 rounded text-sm overflow-x-auto">
                <code>{`// app/layout.js
export const metadata = {
  other: {
    'Content-Security-Policy': 
      "default-src 'self'; " +
      "script-src 'self' 'unsafe-eval' 'unsafe-inline'; " +
      "style-src 'self' 'unsafe-inline'; " +
      "img-src 'self' blob: data: https:; " +
      "font-src 'self' data:; " +
      "connect-src 'self' https://api.yourdomain.com"
  }
}`}</code>
              </pre>
            </div>
            
            <div className="bg-white rounded p-4">
              <h3 className="font-semibold mb-2">4. Rate Limiting</h3>
              <pre className="bg-gray-900 text-white p-3 rounded text-sm overflow-x-auto">
                <code>{`// app/api/protected/route.js
import { rateLimit } from '@/lib/rate-limit'

const limiter = rateLimit({
  interval: 60 * 1000, // 1분
  uniqueTokenPerInterval: 500, // 최대 500개의 고유 토큰
})

export async function POST(request) {
  try {
    await limiter.check(request, 10) // 분당 10회 제한
    // API 로직
  } catch {
    return Response.json(
      { error: 'Too many requests' },
      { status: 429 }
    )
  }
}`}</code>
              </pre>
            </div>
          </div>
        </div>
        
        <div className="bg-white rounded-lg shadow-md p-6">
          <h2 className="text-xl font-semibold mb-4">📋 보안 점검 항목</h2>
          
          <div className="space-y-3">
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>모든 API 키와 비밀번호가 환경 변수로 관리되고 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>.env.local 파일이 .gitignore에 포함되어 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>사용자 입력을 적절히 검증하고 sanitize하고 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>HTTPS를 사용하도록 설정되어 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>인증과 권한 부여가 올바르게 구현되어 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>SQL 인젝션, XSS, CSRF 공격에 대한 방어가 되어 있습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>에러 메시지에 민감한 정보가 노출되지 않습니까?</span>
            </label>
            
            <label className="flex items-start">
              <input type="checkbox" className="mt-1 mr-3" />
              <span>의존성 패키지들이 최신 버전으로 업데이트되어 있습니까?</span>
            </label>
          </div>
        </div>
      </div>
    </div>
  )
}

최종 배포 전 테스트

// app/final-test/page.js
'use client'

import { useState } from 'react'

export default function FinalTestPage() {
  const [testResults, setTestResults] = useState({})
  
  const runTest = async (testName) => {
    setTestResults(prev => ({ ...prev, [testName]: 'running' }))
    
    // 실제로는 각 테스트에 맞는 로직 구현
    await new Promise(resolve => setTimeout(resolve, 1500))
    
    setTestResults(prev => ({ 
      ...prev, 
      [testName]: Math.random() > 0.2 ? 'passed' : 'failed' 
    }))
  }
  
  const tests = [
    { id: 'build', name: '프로덕션 빌드 성공', command: 'npm run build' },
    { id: 'start', name: '프로덕션 서버 실행', command: 'npm run start' },
    { id: 'env', name: '환경 변수 확인', command: 'console.log(process.env)' },
    { id: 'api', name: 'API 엔드포인트 테스트', command: 'fetch("/api/health")' },
    { id: 'lighthouse', name: 'Lighthouse 점수', command: 'lighthouse URL' },
    { id: 'mobile', name: '모바일 반응형 테스트', command: 'Chrome DevTools' }
  ]
  
  const getStatusIcon = (status) => {
    switch(status) {
      case 'passed': return '✅'
      case 'failed': return '❌'
      case 'running': return '⏳'
      default: return '⭕'
    }
  }
  
  const runAllTests = async () => {
    for (const test of tests) {
      await runTest(test.id)
    }
  }
  
  return (
    <div className="min-h-screen bg-gray-50 p-8">
      <div className="max-w-4xl mx-auto">
        <h1 className="text-3xl font-bold mb-8">🎯 최종 배포 테스트</h1>
        
        <div className="bg-white rounded-lg shadow-md p-6 mb-6">
          <div className="flex justify-between items-center mb-6">
            <h2 className="text-xl font-semibold">테스트 실행</h2>
            <button
              onClick={runAllTests}
              className="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700"
            >
              모든 테스트 실행
            </button>
          </div>
          
          <div className="space-y-4">
            {tests.map(test => (
              <div key={test.id} className="border rounded-lg p-4">
                <div className="flex items-center justify-between">
                  <div className="flex items-center space-x-3">
                    <span className="text-2xl">
                      {getStatusIcon(testResults[test.id])}
                    </span>
                    <div>
                      <p className="font-semibold">{test.name}</p>
                      <code className="text-sm text-gray-600">{test.command}</code>
                    </div>
                  </div>
                  <button
                    onClick={() => runTest(test.id)}
                    className="px-4 py-1 bg-gray-100 rounded hover:bg-gray-200"
                    disabled={testResults[test.id] === 'running'}
                  >
                    {testResults[test.id] === 'running' ? '실행 중...' : '테스트'}
                  </button>
                </div>
              </div>
            ))}
          </div>
        </div>
        
        <div className="bg-green-50 border border-green-200 rounded-lg p-6">
          <h2 className="text-xl font-semibold text-green-800 mb-4">
            ✅ 배포 준비 완료 체크리스트
          </h2>
          
          <div className="grid md:grid-cols-2 gap-4">
            <div>
              <h3 className="font-semibold mb-2">기술적 준비</h3>
              <ul className="space-y-1 text-sm text-gray-700">
                <li>• 모든 테스트 통과</li>
                <li>• 환경 변수 설정 완료</li>
                <li>• 에러 페이지 구현</li>
                <li>• 로깅 시스템 구축</li>
                <li>• 백업 계획 수립</li>
              </ul>
            </div>
            
            <div>
              <h3 className="font-semibold mb-2">비즈니스 준비</h3>
              <ul className="space-y-1 text-sm text-gray-700">
                <li>• 도메인 연결 준비</li>
                <li>• SSL 인증서 확인</li>
                <li>• 분석 도구 설정</li>
                <li>• 모니터링 대시보드 준비</li>
                <li>• 롤백 계획 수립</li>
              </ul>
            </div>
          </div>
        </div>
      </div>
    </div>
  )
}

결론

축하합니다! 이제 여러분의 Next.js 애플리케이션은 실제 사용자들을 맞이할 준비가 완료되었습니다. 이번 챕터에서 우리는 프로덕션 빌드의 이해부터 시작하여, 환경 변수 설정, 성능 최적화, 보안 강화, 그리고 최종 테스트까지 배포에 필요한 모든 준비 과정을 상세히 살펴보았습니다.

배포 준비는 단순히 기술적인 작업만이 아닙니다. 사용자 경험, 성능, 보안, 그리고 유지보수까지 고려해야 하는 종합적인 과정입니다. 체크리스트를 하나씩 확인하면서 놓친 부분이 없는지 꼼꼼히 점검하시기 바랍니다.

특히 환경 변수 관리와 보안 설정은 절대 소홀히 해서는 안 됩니다. 한 번의 실수로 민감한 정보가 노출되거나 보안 취약점이 발생할 수 있기 때문입니다. 항상 "보안 우선" 원칙을 기억하시기 바랍니다.

다음 챕터에서는 드디어 Vercel을 통해 실제로 배포하는 과정을 진행하겠습니다. 여러분이 만든 웹사이트가 전 세계에 공개되는 순간이 얼마 남지 않았습니다!