Vercel 환경 변수 적용 안됨 해결 방법

Vercel 배포 시 환경 변수가 undefined로 나온다면 로컬 .env 파일만 확인하지 말고 대시보드 등록 상태를 점검해야 합니다. Vercel은 로컬 .env 파일을 직접 읽지 않으며, 저장소 설정을 통해 값을 받습니다. 대시보드에서 환경 변수를 추가한 뒤 재배포하면 적용됩니다. 웹살림에서 다른 배포 문제 해결법도 확인해 보세요.

문제 확인: .env 파일이 Vercel에서 읽히지 않음

Vercel은 깃 저장소를 기준으로 배포합니다. 그런데 대부분의 프로젝트에서 .env 파일은 .gitignore에 포함되어 있기 때문에, 깃에 업로드되지 않아 Vercel 서버에서는 존재하지 않는 파일입니다. 따라서 로컬에서만 환경 변수를 읽을 수 있고, 배포된 환경에서는 undefined 오류가 발생합니다(출처). 이 문제를 해결하려면 Vercel의 프로젝트 설정에서 직접 변수를 등록해야 합니다.

해결 방법

Vercel 대시보드에서 환경 변수를 추가하고 코드를 확인하는 단계별 가이드입니다.

1. Vercel 대시보드에서 환경 변수 추가하기

프로젝트의 Settings → Environment Variables 메뉴로 이동합니다. 여기에 .env에 있던 키와 값을 그대로 입력합니다. Vercel은 저장소 설정을 통해 환경 변수를 받기 때문에, 이 과정이 필수입니다(출처). UI에서 추가한 모든 변수는 기본적으로 Private(비공개)로 처리되므로, 서버에서만 접근 가능합니다(출처).

2. 공개 변수는 `PUBLIC_` 접두사 사용하기

클라이언트 사이드에서도 접근해야 하는 값(예: 공개 API 엔드포인트)이 있다면, 변수명 앞에 PUBLIC_를 붙이고, 코드에서는 $env/static/public에서 import 하세요. 이 방식은 로컬 개발과 동일하게 Vercel에서도 작동합니다(출처).

// 예: src/lib/config.js
import { PUBLIC_API_BASE } from '$env/static/public';

export const apiClient = {
  base: PUBLIC_API_BASE
};

3. 환경 변수 추가 후 반드시 재배포하기

환경 변수를 대시보드에서 추가했더라도, 적용을 위해서는 반드시 재배포해야 합니다. 추가 후 Deploy 버튼을 눌러 새로운 배포를 생성하세요(출처). 이 단계를 건너뛰면 기존 배포에는 새 변수가 반영되지 않습니다.

참고: Vercel 무료 플랜에서도 환경 변수 사용 가능

Vercel은 취미 프로젝트를 위한 무료 플랜(Hobby)을 제공하며, 해당 플랜에서도 환경 변수 기능을 제한 없이 이용할 수 있습니다(출처). 따라서 소규모 프로젝트나 개인 블로그에서도 안심하고 적용하세요.

참고 자료

Vercel 환경 변수 미적용 원인 분석 (h-owo-ld.tistory.com, 2026-07-27 확인)
Vercel 대시보드 환경 변수 설정 방법 (oneyenee.tistory.com, 2026-07-27 확인)
Public 변수 동작에 관한 커뮤니티 답변 (Reddit, 2026-07-27 확인)
환경 변수 추가 후 재배포 필요성 (velog.io, 2026-07-27 확인)