Vercel CLI 로컬 개발 설정

Introduction

Vercel CLI는 로컬 환경에서 Vercel 프로젝트를 개발하고 테스트하는 데 유용한 도구입니다. 이 글에서는 Vercel CLI를 설정하고 로컬 개발 환경을 최적화하는 방법을 알아보겠습니다.

Environment

Vercel CLI 30+
Node.js 18+
macOS/Linux/Windows
Git

Problem

Vercel CLI 설정이 올바르지 않을 때 발생하는 문제:

$ vercel dev
Error: Not logged in. Run `vercel login` first.

$ vercel login
Error: Authentication failed. Please check your credentials.

Analysis

Vercel CLI의 주요 기능:

로컬 개발 서버: Vercel 환경과 유사한 로컬 서버
환경 변수 동기화: Vercel 프로젝트의 환경 변수 가져오기
배포 관리: CLI에서 직접 배포 가능
프로젝트 설정: 프로젝트 설정 관리

Solution

1. Vercel CLI 설치

# npm으로 설치
npm install -g vercel

# 또는 yarn으로 설치
yarn global add vercel

# 설치 확인
vercel --version

2. 로그인 및 인증

# 브라우저를 통한 로그인
vercel login

# 토큰을 사용한 로그인 (CI/CD 환경)
export VERCEL_TOKEN=your-token-here

# 로그인 상태 확인
vercel whoami

3. 프로젝트 연결

# 기존 프로젝트에 연결
vercel link

# 새 프로젝트 생성
vercel

# 프로젝트 정보 확인
vercel project ls

4. 로컬 개발 서버 실행

# 개발 서버 시작
vercel dev

# 특정 포트로 시작
vercel dev --port 3001

# 환경 변수 동기화하여 시작
vercel dev --env .env.local

5. 환경 변수 관리

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

# 환경 변수 추가
vercel env add DATABASE_URL

# 환경 변수 목록 확인
vercel env ls

# 환경 변수 삭제
vercel env rm DATABASE_URL

6. 로컬 설정 파일

// .vercel/project.json (자동 생성)
{
  "orgId": "your-org-id",
  "projectId": "your-project-id"
}

// vercel.json 로컬 설정
{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/next"
    }
  ],
  "routes": [
    {
      "src": "/api/(.*)",
      "dest": "/api/$1"
    }
  ]
}

7. 빌드 및 배포 테스트

# 로컬 빌드 테스트
vercel build

# 프로덕션 빌드 테스트
vercel build --prod

# 프리뷰 배포
vercel

# 프로덕션 배포
vercel --prod

8. 로깅 및 디버깅

# 상세 로깅
vercel dev --debug

# 함수 로그 확인
vercel logs

# 특정 함수 로그
vercel logs --function=api/users

9. 환경 변수 검증 스크립트

// scripts/verify-env.js
const { execSync } = require('child_process');

function verifyEnvironment() {
  try {
    // Vercel 환경 변수 가져오기
    execSync('vercel env pull .env.local --yes', { stdio: 'inherit' });
    
    // 환경 변수 로드
    require('dotenv').config();
    
    // 필수 환경 변수 확인
    const required = ['DATABASE_URL', 'API_KEY'];
    const missing = required.filter(key => !process.env[key]);
    
    if (missing.length > 0) {
      console.error('Missing environment variables:', missing);
      process.exit(1);
    }
    
    console.log('Environment verification passed');
  } catch (error) {
    console.error('Environment verification failed:', error.message);
    process.exit(1);
  }
}

verifyEnvironment();

10. Git hooks 통합

// package.json
{
  "scripts": {
    "precommit": "lint-staged",
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,ts,jsx,tsx}": ["eslint --fix", "prettier --write"]
  }
}

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

Lessons Learned

토큰 관리: Vercel 토큰은 안전한 곳에 저장하고, 공유하지 않아야 합니다.
환경 변수 동기화: 로컬 개발 시 Vercel 환경 변수를 동기화하면 일관된 개발이 가능합니다.
빌드 테스트: 배포 전에 로컬에서 빌드를 테스트하면 문제를 조기에 발견할 수 있습니다.
Git hooks: Git hooks를 활용하면 커밋 전에 코드 품질을 검증할 수 있습니다.
** 문서화**: 팀원들을 위한 설정 문서를 작성하면 온보딩이 용이합니다.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.