Vercel에서 환경 변수(ENV) 설정 방법

Introduction

Vercel에서 프로젝트를 배포할 때 환경 변수를 올바르게 설정하는 것은 보안과 기능에 중요합니다. 이번 포스트에서는 Vercel에서 환경 변수를 설정하는 여러 방법을 살펴보겠습니다.

Environment

# Vercel CLI
vercel --version
# 33.0.0

# 프로젝트 구조
my-app/
├── .env.local
├── .env.development
├── .env.production
└── vercel.json

Problem

환경 변수가 올바르게 로드되지 않아 배포 후 기능이 작동하지 않았습니다:

// 기존 코드
const apiKey = process.env.API_KEY;
console.log(apiKey); // undefined

Solution

1. Vercel 대시보드 설정

1. Vercel 대시보드 접속
2. 프로젝트 선택
3. Settings > Environment Variables 탭
4. 환경 변수 추가
   - Key: API_KEY
   - Value: sk-your-api-key
   - Environments: Production, Preview, Development
5. Save 클릭

2. Vercel CLI 설정

# 환경 변수 추가
$ vercel env add API_KEY

# 특정 환경에 추가
$ vercel env add API_KEY production
$ vercel env add API_KEY preview

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

# 환경 변수 제거
$ vercel env rm API_KEY

3. .env 파일 구조

# .env.local (로컬 개발용, Git에 커밋되지 않음)
API_KEY=sk-local-key
DATABASE_URL=postgresql://localhost:5432/mydb

# .env.development (개발 환경)
NEXT_PUBLIC_API_URL=http://localhost:3000

# .env.production (프로덕션)
NEXT_PUBLIC_API_URL=https://myapp.vercel.app

4. 코드에서 환경 변수 사용

// 서버 측 환경 변수
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;

// 클라이언트 측 환경 변수 (NEXT_PUBLIC_ 접두사 필요)
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// 환경 변수 검증
function validateEnv() {
    const required = ['API_KEY', 'DATABASE_URL'];

    for (const key of required) {
        if (!process.env[key]) {
            throw new Error(`Missing environment variable: ${key}`);
        }
    }
}

validateEnv();

5. vercel.json 환경 설정

{
    "env": {
        "API_KEY": "@api-key",
        "DATABASE_URL": "@database-url"
    },
    "buildEnv": {
        "NODE_ENV": "production"
    }
}

6. 런타임 환경 변수

// Vercel Runtime에서 환경 변수 가져오기
const { VercelRequest, VercelResponse } = require('@vercel/node');

module.exports = async (req, res) => {
    const apiKey = process.env.API_KEY;

    if (!apiKey) {
        return res.status(500).json({ error: 'API key not configured' });
    }

    // API 사용
    const result = await callExternalAPI(apiKey);
    res.json(result);
};

Lessons Learned

1. 보안 관리: 비밀 키는 Git에 커밋하지 말고 Vercel 대시보드에서 관리하세요
2. 환경 구분: Development, Preview, Production 환경을 구분하여 설정하세요
3. NEXT_PUBLIC_ 접두사: 클라이언트에서 사용할 변수는 NEXT_PUBLIC_을 접두사로 사용하세요
4. 검증 로직: 앱 시작 시 필수 환경 변수가 설정되어 있는지 검증하세요
5. 변경 이력 관리: 환경 변수 변경 시 이력을 관리하여 문제 발생 시 추적하세요

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