Vercel Deployment Skill

Vercel 배포 및 서버리스 인프라 관리를 위한 전문 스킬입니다.

Quick Start

# Vercel CLI 설치
npm install -g vercel

# 로그인
vercel login

# 프로젝트 연결
vercel link

# 배포 (Preview)
vercel

# 배포 (Production)
vercel --prod

환경 변수 설정

필수 환경 변수

토큰 생성

Vercel Dashboard > Settings > Tokens > Create Token
├── Name: claude-deploy (또는 원하는 이름)
├── Scope: Full Account (또는 특정 프로젝트)
└── Expiration: No Expiration (또는 기간 설정)

핵심 기능

1. 배포 명령어

# Preview 배포 (기본)
vercel

# Production 배포
vercel --prod

# 특정 환경 변수와 함께 배포
vercel --env KEY=value --env KEY2=value2

# 빌드 스킵 (이미 빌드된 경우)
vercel --prebuilt

# 배포 후 URL 출력
vercel --prod 2>&1 | tail -1

2. 프로젝트 구조

project/
├── vercel.json          # Vercel 설정
├── .vercel/
│   └── project.json     # 프로젝트 연결 정보
├── api/                 # Serverless Functions
│   ├── hello.ts
│   └── users/
│       └── [id].ts
├── public/              # 정적 파일
└── src/                 # 앱 소스

3. vercel.json 설정

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "installCommand": "npm install",

  "regions": ["icn1"],

  "env": {
    "NODE_ENV": "production"
  },

  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" }
      ]
    }
  ],

  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "permanent": true
    }
  ],

  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "https://api.example.com/:path*"
    }
  ]
}

4. Serverless Functions

기본 함수

// api/hello.ts
import type { VercelRequest, VercelResponse } from '@vercel/node';

export default function handler(req: VercelRequest, res: VercelResponse) {
  const { name = 'World' } = req.query;
  res.status(200).json({ message: `Hello ${name}!` });
}

동적 라우트

// api/users/[id].ts
import type { VercelRequest, VercelResponse } from '@vercel/node';

export default function handler(req: VercelRequest, res: VercelResponse) {
  const { id } = req.query;
  res.status(200).json({ userId: id });
}

Edge Function

// api/edge-hello.ts
export const config = {
  runtime: 'edge',
};

export default function handler(request: Request) {
  return new Response(
    JSON.stringify({ message: 'Hello from Edge!' }),
    {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    }
  );
}

5. 환경 변수 관리

CLI로 관리

# 환경 변수 추가
vercel env add MY_VAR production
vercel env add MY_VAR preview
vercel env add MY_VAR development

# 환경 변수 목록
vercel env ls

# 환경 변수 삭제
vercel env rm MY_VAR production

# 로컬로 환경 변수 가져오기
vercel env pull .env.local

환경별 설정

6. 도메인 관리

# 도메인 추가
vercel domains add example.com

# 도메인 목록
vercel domains ls

# 도메인 제거
vercel domains rm example.com

# DNS 레코드 확인
vercel dns ls example.com

7. 로컬 개발

# Vercel 환경으로 로컬 실행
vercel dev

# 특정 포트로 실행
vercel dev --listen 3000

# 환경 변수 포함
vercel dev --env .env.local

CI/CD 통합

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy to Vercel

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Vercel CLI
        run: npm install -g vercel

      - name: Pull Vercel Environment
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Preview
        if: github.event_name == 'pull_request'
        run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy Production
        if: github.ref == 'refs/heads/main'
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

환경별 빌드

# Preview 환경 빌드
vercel build

# Production 환경 빌드
vercel build --prod

# Prebuilt로 배포 (빌드 결과물만)
vercel deploy --prebuilt --prod

CLI 명령어 참조

체크리스트

초기 설정

• Vercel CLI 설치 (npm i -g vercel)
• 로그인 (vercel login)
• 프로젝트 연결 (vercel link)
• 환경 변수 설정 (Dashboard 또는 CLI)

배포 전

• vercel.json 설정 확인
• 환경 변수 확인 (vercel env ls)
• 로컬 빌드 테스트 (vercel build)
• 로컬 실행 테스트 (vercel dev)

Production 배포

• Preview 배포 테스트
• 환경 변수 Production 설정
• 도메인 설정 (필요시)
• vercel --prod 실행

Anti-Patterns

연동

트러블슈팅

빌드 실패

# 로컬에서 빌드 테스트
vercel build

# 빌드 로그 확인
vercel logs <deployment-url>

# 캐시 초기화
vercel deploy --force

환경 변수 누락

# 현재 환경 변수 확인
vercel env ls

# 로컬로 동기화
vercel env pull .env.local

# 특정 환경 변수 확인
vercel env ls | grep MY_VAR

함수 타임아웃

// vercel.json에서 함수별 설정
{
  "functions": {
    "api/long-task.ts": {
      "maxDuration": 60  // 최대 60초 (Pro 플랜)
    }
  }
}

CORS 오류

// vercel.json
{
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Credentials", "value": "true" },
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Access-Control-Allow-Methods", "value": "GET,POST,PUT,DELETE,OPTIONS" },
        { "key": "Access-Control-Allow-Headers", "value": "Content-Type, Authorization" }
      ]
    }
  ]
}

참조 문서

• Vercel CLI Overview
• Vercel Deploy Command
• Deploying from CLI