배포 매뉴얼
전체 목차05 · 환경 변수
Chapter 05

환경 변수

최종 확인일 2026-11-04 읽는 시간 약 8분 설정 · 빌드와 환경 변수

목표#

  • 환경 변수가 무엇이고 왜 코드에 직접 쓰면 안 되는지 이해합니다.
  • Vercel 대시보드에서 Production / Preview / Development 환경별로 환경 변수를 설정합니다.
  • 브라우저에 노출되는 변수와 서버에서만 쓰는 변수를 구분합니다.
  • 로컬 개발 환경에서 같은 환경 변수를 사용하는 방법을 알아 둡니다.

사전 조건#

  • 3장에서 프로젝트를 배포했습니다.
  • 설정할 값(API 키, 데이터베이스 주소 등)이 준비되어 있습니다.

1. 환경 변수란?#

환경 변수는 코드 밖에서 주입하는 설정 값입니다. 코드에서는 이름으로만 불러 씁니다.

JavaScript
// 코드에는 값이 아니라 이름만 적습니다.
const apiKey = process.env.WEATHER_API_KEY;
코드에 직접 쓰면환경 변수로 분리하면
GitHub에 비밀 값이 그대로 올라감비밀 값은 Vercel에만 저장
운영/테스트 값을 바꾸려면 코드 수정 필요환경마다 다른 값을 설정 가능
키를 교체할 때마다 커밋 필요대시보드에서 값만 바꾸고 재배포

2. Vercel의 세 가지 환경#

환경언제 사용되나요?예시 값
Productionmain 브랜치 배포 (실제 서비스)운영 DB 주소, 실제 결제 키
Previewmain 이외 브랜치·PR 배포 (6장)테스트 DB 주소, 테스트 결제 키
Development로컬 PC에서 vercel env pull / vercel dev로 개발할 때 (8장)로컬용 값
팁

Preview에 운영 데이터베이스 값을 넣으면, 실험 중인 브랜치가 실제 데이터를 바꿔 버릴 수 있습니다. 가능하면 Production과 Preview에 서로 다른 값을 쓰세요.


3. 환경 변수 추가하기#

  1. Vercel 프로젝트에서 Settings → Environment Variables로 이동합니다.
  2. Key에 변수 이름을 입력합니다. 예: WEATHER_API_KEY

    • 영문 대문자, 숫자, 밑줄(_)을 쓰는 것이 관례입니다.
  3. Value에 값을 입력합니다.
  4. 적용할 Environments를 선택합니다. (Production / Preview / Development 중 선택)

    • Preview는 특정 브랜치에만 적용하도록 지정할 수도 있습니다.
  5. 비밀 값이라면 Sensitive 옵션을 켭니다. 저장 후에는 대시보드에서도 값을 다시 볼 수 없습니다.
  6. Save를 누릅니다.
팁

로컬의 .env 파일 내용을 통째로 복사해 Key 입력란에 붙여 넣으면 여러 변수가 한 번에 입력됩니다.

4. 재배포해서 적용하기#

중요

환경 변수를 추가하거나 바꿔도 이미 끝난 배포에는 반영되지 않습니다. 반드시 다시 배포해야 합니다.

  1. Deployments 탭으로 이동합니다.
  2. 최신 Production 배포 오른쪽의 ⋯ 메뉴에서 Redeploy를 누릅니다.
  3. 배포가 Ready가 되면 새 값이 적용됩니다.

또는 새 커밋을 push해도 됩니다.


5. 브라우저에 노출되는 변수 vs 서버 전용 변수#

프레임워크는 특정 접두사가 붙은 변수만 브라우저용 코드에 넣습니다. 접두사가 붙은 변수는 누구나 브라우저 개발자 도구에서 볼 수 있습니다.

프레임워크브라우저 노출 접두사코드에서 읽는 법
Next.jsNEXT_PUBLIC_process.env.NEXT_PUBLIC_API_URL
ViteVITE_import.meta.env.VITE_API_URL
Create React AppREACT_APP_process.env.REACT_APP_API_URL
NuxtNUXT_PUBLIC_useRuntimeConfig().public.apiUrl
구분예시접두사
공개해도 되는 값공개 API 주소, 지도 SDK 공개 키붙임
비밀 값DB 비밀번호, 서버용 API 비밀 키, 결제 비밀 키절대 붙이지 않음
주의

NEXT_PUBLIC_SECRET_KEY처럼 비밀 값에 노출 접두사를 붙이면 Vercel에 안전하게 저장해도 배포된 JavaScript 파일 안에 그대로 들어가 공개됩니다. 비밀 값은 서버 코드(API Route, Server Component 등)에서만 사용하세요.

참고

브라우저 노출 변수는 빌드할 때 코드에 박혀 들어갑니다. 값을 바꾸면 반드시 재배포해야 합니다.


6. Vercel이 자동으로 넣어 주는 변수 (System Environment Variables)#

직접 설정하지 않아도 Vercel이 배포마다 자동으로 제공하는 변수가 있습니다.

변수값 예시용도
VERCEL_ENVproduction / preview / development현재 환경에 따라 동작 분기
VERCEL_URLmy-app-abc123-team.vercel.app현재 배포의 고유 주소 (https:// 없음)
VERCEL_GIT_COMMIT_REFmain, feature/login배포된 브랜치 이름
VERCEL_GIT_COMMIT_SHAabc1234...배포된 커밋
JavaScript
if (process.env.VERCEL_ENV === 'production') {
  // 운영에서만 실행할 코드
}
참고

이 변수들은 서버·빌드 환경에서 사용할 수 있습니다. 브라우저 코드에서 쓰려면 프레임워크별 노출 접두사가 붙은 변수를 사용해야 합니다. (예: Next.js의 NEXT_PUBLIC_VERCEL_ENV)


7. 로컬 개발에서 환경 변수 사용하기#

로컬에서는 프로젝트 최상단의 .env.local 파일에 값을 둡니다.

bash
# .env.local  (절대 커밋하지 않음)
WEATHER_API_KEY=<YOUR_API_KEY>
NEXT_PUBLIC_API_URL=http://localhost:3000/api

팀원에게는 이름만 적은 .env.example을 커밋해 어떤 변수가 필요한지 알려 줍니다.

bash
# .env.example  (커밋함, 값은 비워 둠)
WEATHER_API_KEY=
NEXT_PUBLIC_API_URL=
팁

Vercel CLI를 쓰면 Vercel에 저장된 Development 환경 변수를 .env.local로 바로 내려받을 수 있습니다.

bash
vercel env pull

자세한 내용은 8장 Vercel CLI를 참고하세요.

주의

.env.local이 .gitignore에 포함되어 있는지 꼭 확인하세요. (1장의 .gitignore 예시 참고)


확인 방법#

문제 해결#

증상원인과 해결
값이 undefined로 나옴변수 추가 후 재배포하지 않음 → Redeploy
Production에선 되는데 Preview에선 undefinedPreview 환경에 체크하지 않음 → 변수 편집에서 Preview 선택
브라우저 코드에서만 undefined노출 접두사 누락 → 공개해도 되는 값이면 NEXT_PUBLIC_ 등 추가
로컬에선 되는데 Vercel에선 안 됨.env.local 값만 있고 Vercel에 등록하지 않음 → 3단계 진행
변수 이름을 바꿨더니 빌드 실패코드 속 이름과 Vercel 이름의 대소문자·철자 불일치 확인

다음 단계#

➡️ 6장. Preview 배포와 PR 흐름: 브랜치와 PR을 이용해 운영 사이트에 영향 없이 변경 사항을 미리 확인합니다.

참고 자료#