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

Vercel 배포 시 환경 변수가 적용되지 않는 문제는 대부분 .env 파일이 버전 관리에서 제외되어 Vercel이 읽지 못하기 때문에 발생합니다. 해결하려면 Vercel 대시보드에서 환경 변수를 직접 추가하고 프로젝트를 재배포해야 합니다. 공개 변수를 사용해야 한다면 프레임워크에 따라 올바른 접두사 규칙을 따라야 합니다.

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

Vercel은 Git 기반의 지속적 배포(Continuous Deployment)를 채택하고 있어, 깃 저장소에 푸시된 코드를 기반으로 빌드합니다. 이 과정에서 .gitignore 파일에 명시된 파일은 저장소에서 제외되어 Vercel 빌드 서버로 전송되지 않습니다. 로컬 개발 환경에서는 프로젝트 루트에 위치한 .env 파일을 프레임워크가 자동으로 읽어 들여 환경 변수를 설정하지만, Vercel은 배포 시점에 저장소의 파일만 바라보기 때문에 .gitignore에 등록된 .env 파일은 존재하지 않는 파일로 간주합니다. Vercel은 .gitignore에 등록된 .env 파일을 저장소에서 읽지 않기 때문에 환경 변수가 적용되지 않습니다. 따라서 배포된 애플리케이션에서 process.env.SOME_KEY와 같은 변수가 undefined로 평가되거나 예상치 못한 동작이 발생하는 일이 빈번하게 일어납니다.

많은 개발자가 로컬에서 문제없이 작동하는 코드가 배포 후에만 이상해지는 상황을 경험하는데, 이는 환경 변수 의존성 때문인 경우가 대부분입니다. 특히 API 키, 데이터베이스 연결 문자열, 서드파티 서비스 인증 정보 등은 로컬 .env에만 정의되어 있기 때문에 Vercel 배포 환경에서는 접근할 수 없게 됩니다. 이 문제의 근본 원인은 Vercel이 애플리케이션 빌드를 위한 격리된 샌드박스 환경을 제공하며, 외부 .env 파일을 수동으로 주입하지 않으면 기본적으로 아무 변수도 로드하지 않는다는 점입니다. 따라서 .env 파일을 사용하는 로컬 개발 방식에 익숙한 상태에서 Vercel로 이전할 때 반드시 인지해야 하는 차이입니다.

해결 1: Vercel 대시보드에서 환경 변수 추가 (Private 변수)

환경 변수를 Vercel이 인식할 수 있도록 대시보드 설정을 변경해야 합니다. 아래 절차를 순서대로 따르면 쉽게 등록할 수 있습니다.

Vercel 대시보드(https://vercel.com)에 로그인한 후, 프로젝트 목록에서 문제가 발생한 프로젝트를 선택합니다. 프로젝트가 많다면 검색 기능을 활용할 수 있습니다.
선택한 프로젝트의 상단 탭 중 Settings를 클릭합니다. Settings 탭은 프로젝트의 전반적인 구성을 담당합니다.
왼쪽 사이드바 메뉴에서 Environment Variables 항목을 찾아 선택합니다. 이 메뉴가 보이지 않으면, 프로젝트 권한이 충분한지 확인해 보세요.
Key 입력란에는 환경 변수의 이름을, Value 입력란에는 실제 값을 입력합니다. 예를 들어 API_KEY라는 키와 abcdef123456 같은 실제 키 값을 입력합니다. Key는 대소문자를 구분하므로 프레임워크에서 사용하는 그대로 입력해야 합니다.
바로 아래 Environment 섹션에서 이 변수가 적용될 배포 환경을 선택합니다. Production, Preview, Development 세 가지 옵션이 있으며, 보통 Production과 Preview에 동시에 설정하는 것이 일반적입니다. Development 환경은 로컬 개발에서 사용하는 Vercel CLI와 연동됩니다.
값이 민감한 경우에는 Encrypted라고 표시된 부분이 자동으로 활성화되어, 대시보드에서도 가려져 보입니다. 이 기능은 보안을 위한 것으로 별도의 설정이 필요 없습니다.
모든 입력이 끝나면 오른쪽 하단의 Save 버튼을 클릭합니다. 저장 후에는 변수가 목록에 추가된 것을 확인할 수 있습니다.

이렇게 추가된 환경 변수는 서버 측 빌드 과정에 주입되며, 기본적으로 비공개(private) 변수로 처리됩니다. Vercel 대시보드에서 추가하는 모든 환경 변수는 기본적으로 비공개(private)로 선언됩니다. 즉, 빌드된 자바스크립트 번들에는 포함되지 않으므로 브라우저의 개발자 도구에서 노출될 염려가 없습니다. 서버사이드 렌더링(SSR)이나 API 라우트에서만 접근할 수 있기 때문에, 데이터베이스 비밀번호나 내부 API 키처럼 절대 외부로 새어 나가면 안 되는 값들에 적합합니다. 만약 클라이언트 측에서도 접근해야 하는 변수(예: 구글 애널리틱스 추적 ID)가 있다면, 다음 절에서 설명하는 공개 변수 방법을 사용해야 합니다.

해결 2: 공개 변수는 올바른 접두사 사용

클라이언트 자바스크립트에서 직접 환경 변수를 읽어야 하는 상황은 생각보다 자주 발생합니다. 대표적으로 구글 애널리틱스 ID, 지도 서비스 API 키, 공개 API 엔드포인트 등이 있습니다. Vercel은 이러한 공개 변수를 지원하기 위해 프레임워크별 네이밍 컨벤션을 따르도록 유도합니다. SvelteKit, Next.js, Nuxt, Gatsby 등 주류 프레임워크는 모두 고유한 접두사 규칙을 가지고 있으며, 접두사를 지키지 않으면 Vercel에서 자동으로 private 변수로 간주하여 주입을 차단합니다.

예를 들어 SvelteKit의 경우, Vercel에서 공개 환경 변수는 로컬과 동일하게 PUBLIC_ 접두사를 사용하고 $env/static/public에서 임포트하면 작동합니다. 따라서 PUBLIC_ANALYTICS_ID와 같은 이름으로 대시보드에 등록한 후, 코드에서 import { PUBLIC_ANALYTICS_ID } from '$env/static/public'; 구문으로 사용하면 됩니다. Next.js에서는 NEXT_PUBLIC_ 접두사가 필요하며, 예를 들어 NEXT_PUBLIC_GOOGLE_ANALYTICS_ID 형태로 등록하고 클라이언트 컴포넌트에서 process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID로 접근합니다. Nuxt.js는 NUXT_PUBLIC_ 접두사를, Astro는 PUBLIC_ 접두사를 사용하는 식으로 프레임워크마다 규칙이 다릅니다.

따라서 공개 변수를 사용해야 한다면, 반드시 본인이 사용하는 프레임워크의 공식 문서에서 명시한 접두사 규칙을 먼저 확인하세요. 접두사를 붙이지 않은 변수는 Vercel이 private으로 분류하기 때문에, 아무리 대시보드에 등록해도 클라이언트에서는 읽을 수 없습니다. 브라우저 콘솔에서 undefined가 출력된다면 접두사 누락을 의심해 보시기 바랍니다. 또한, 접두사를 붙이는 시점은 대시보드에서 Key를 입력할 때여야 하며, 로컬 .env 파일에서도 동일한 Key를 사용해야 개발 환경과 배포 환경의 일관성이 유지됩니다.

필수: 환경 변수 추가 후 재배포

Vercel에서 환경 변수를 추가하거나 수정한 후 많은 개발자가 간과하는 중요한 단계가 바로 재배포입니다. 환경 변수는 빌드 타임에 주입되기 때문에, 이미 생성된 배포본에는 변경 사항이 전혀 반영되지 않습니다. Vercel 대시보드에서 환경 변수를 추가한 후에는 반드시 프로젝트를 재배포해야 적용됩니다.

재배포는 매우 간단합니다. 다음 두 가지 방법 중 하나를 선택하세요.

대시보드에서의 수동 재배포: 프로젝트 페이지의 Deployments 탭으로 이동합니다. 배포 목록이 시간순으로 표시되는데, 가장 최근 커밋(보통 맨 위)을 클릭합니다. 배포 상세 화면 오른쪽 상단에 있는 Redeploy 버튼을 클릭하면 동일한 커밋으로 새 빌드가 시작됩니다. 이 과정에서 최신 환경 변수가 주입됩니다.
Git을 통한 자동 배포: 로컬에서 아무런 코드 변경 없이 빈 커밋이라도 생성하여 깃허브 등에 푸시하면 Vercel이 자동 감지하여 새 배포를 실행합니다. 예를 들어 git commit --allow-empty -m "env variables update" 명령 후 git push 하는 방법이 간편합니다.

재배포가 완료되면 해당 배포의 빌드 로그를 확인하여 환경 변수가 올바르게 로드되었는지 검토하는 습관을 들이세요. Vercel 빌드 로그에는 주입된 변수의 수나, 프레임워크가 변수를 치환하는 과정이 표시될 때도 있습니다. 로그에서 Environment variables - Loading... 같은 메시지가 나타나면 정상입니다.

재배포를 잊어버리는 실수는 숙련된 개발자에게도 흔하게 발생합니다. 특히 여러 환경 변수를 한 번에 추가했을 때, 배포를 트리거하지 않고 “저장했으니 당연히 적용되겠지”라고 생각하는 경우가 많습니다. 환경 변수 변경 사항이 적용되려면 항상 새로운 배포가 필요하다는 점을 기억하세요. 또한, 프로젝트에 자동 배포가 설정되어 있지 않다면 수동으로 꼭 재배포 버튼을 눌러야 합니다.

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

Vercel은 취미 프로젝트를 위한 무료 플랜을 제공합니다. 무료 플랜이라고 해서 환경 변수 기능이 제한되는 것은 아니며, 개인 프로젝트에서도 유료 플랜과 동일하게 대시보드에서 환경 변수를 추가하고 관리할 수 있습니다. 환경 변수 개수에 제한이 있는지에 대한 공식 제한 사항은 별도로 발표된 바 없으며, 일반적인 사용량 범위에서는 문제없이 사용 가능합니다.

다만 무료 플랜은 월별 빌드 시간(100시간)과 대역폭(100GB), 서버리스 함수 실행 시간 등의 제한이 있으므로, 프로젝트의 규모가 커지면 Hobby에서 Pro 플랜으로 업그레이드하는 것을 고려해야 합니다. 환경 변수 자체는 요금제와 무관하게 동일하게 제공됩니다.

Vercel은 로컬 .env 파일 대신 대시보드의 저장소 설정에서 환경 변수를 등록해야 합니다. 이 방식은 팀 협업 시 큰 장점으로 작용합니다. 프로젝트에 여러 명이 참여하더라도 각자 로컬에 .env 파일을 따로 관리할 필요 없이, 대시보드에서 중앙 관리된 환경 변수를 모든 배포가 일관되게 참조합니다. 또한 민감한 변수는 대시보드에서 암호화되어 저장되므로 보안 측면에서도 로컬 파일보다 안전합니다. 만약 환경 변수에 버전 이력이 필요하다면, Vercel은 자체적으로 버전 관리를 제공하지 않으므로 변경 사항을 별도로 기록해 두는 것이 좋습니다.

웹 운영과 관련된 더 실용적인 팁은 웹살림에서 확인할 수 있습니다.

참고 자료

Tistory - h-owo-ld — 확인일 2026-07-27
Velog - hyun907 — 확인일 2026-07-27
Reddit - sveltejs — 확인일 2026-07-27
Tistory - oneyenee — 확인일 2026-07-27