목표#
- 환경 변수가 무엇이고 왜 코드에 직접 쓰면 안 되는지 이해합니다.
- Vercel 대시보드에서 Production / Preview / Development 환경별로 환경 변수를 설정합니다.
- 브라우저에 노출되는 변수와 서버에서만 쓰는 변수를 구분합니다.
- 로컬 개발 환경에서 같은 환경 변수를 사용하는 방법을 알아 둡니다.
사전 조건#
- 3장에서 프로젝트를 배포했습니다.
- 설정할 값(API 키, 데이터베이스 주소 등)이 준비되어 있습니다.
1. 환경 변수란?#
환경 변수는 코드 밖에서 주입하는 설정 값입니다. 코드에서는 이름으로만 불러 씁니다.
// 코드에는 값이 아니라 이름만 적습니다.
const apiKey = process.env.WEATHER_API_KEY;| 코드에 직접 쓰면 | 환경 변수로 분리하면 |
|---|---|
| GitHub에 비밀 값이 그대로 올라감 | 비밀 값은 Vercel에만 저장 |
| 운영/테스트 값을 바꾸려면 코드 수정 필요 | 환경마다 다른 값을 설정 가능 |
| 키를 교체할 때마다 커밋 필요 | 대시보드에서 값만 바꾸고 재배포 |
2. Vercel의 세 가지 환경#
| 환경 | 언제 사용되나요? | 예시 값 |
|---|---|---|
| Production | main 브랜치 배포 (실제 서비스) | 운영 DB 주소, 실제 결제 키 |
| Preview | main 이외 브랜치·PR 배포 (6장) | 테스트 DB 주소, 테스트 결제 키 |
| Development | 로컬 PC에서 vercel env pull / vercel dev로 개발할 때 (8장) | 로컬용 값 |
Preview에 운영 데이터베이스 값을 넣으면, 실험 중인 브랜치가 실제 데이터를 바꿔 버릴 수 있습니다. 가능하면 Production과 Preview에 서로 다른 값을 쓰세요.
3. 환경 변수 추가하기#
- Vercel 프로젝트에서 Settings → Environment Variables로 이동합니다.
Key에 변수 이름을 입력합니다. 예:
WEATHER_API_KEY- 영문 대문자, 숫자, 밑줄(
_)을 쓰는 것이 관례입니다.
- 영문 대문자, 숫자, 밑줄(
- Value에 값을 입력합니다.
적용할 Environments를 선택합니다. (Production / Preview / Development 중 선택)
- Preview는 특정 브랜치에만 적용하도록 지정할 수도 있습니다.
- 비밀 값이라면 Sensitive 옵션을 켭니다. 저장 후에는 대시보드에서도 값을 다시 볼 수 없습니다.
- Save를 누릅니다.
로컬의 .env 파일 내용을 통째로 복사해 Key 입력란에 붙여 넣으면 여러 변수가 한 번에 입력됩니다.
4. 재배포해서 적용하기#
환경 변수를 추가하거나 바꿔도 이미 끝난 배포에는 반영되지 않습니다. 반드시 다시 배포해야 합니다.
- Deployments 탭으로 이동합니다.
- 최신 Production 배포 오른쪽의 ⋯ 메뉴에서 Redeploy를 누릅니다.
- 배포가 Ready가 되면 새 값이 적용됩니다.
또는 새 커밋을 push해도 됩니다.
5. 브라우저에 노출되는 변수 vs 서버 전용 변수#
프레임워크는 특정 접두사가 붙은 변수만 브라우저용 코드에 넣습니다. 접두사가 붙은 변수는 누구나 브라우저 개발자 도구에서 볼 수 있습니다.
| 프레임워크 | 브라우저 노출 접두사 | 코드에서 읽는 법 |
|---|---|---|
| Next.js | NEXT_PUBLIC_ | process.env.NEXT_PUBLIC_API_URL |
| Vite | VITE_ | import.meta.env.VITE_API_URL |
| Create React App | REACT_APP_ | process.env.REACT_APP_API_URL |
| Nuxt | NUXT_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_ENV | production / preview / development | 현재 환경에 따라 동작 분기 |
VERCEL_URL | my-app-abc123-team.vercel.app | 현재 배포의 고유 주소 (https:// 없음) |
VERCEL_GIT_COMMIT_REF | main, feature/login | 배포된 브랜치 이름 |
VERCEL_GIT_COMMIT_SHA | abc1234... | 배포된 커밋 |
if (process.env.VERCEL_ENV === 'production') {
// 운영에서만 실행할 코드
}이 변수들은 서버·빌드 환경에서 사용할 수 있습니다. 브라우저 코드에서 쓰려면 프레임워크별 노출 접두사가 붙은 변수를 사용해야 합니다. (예: Next.js의 NEXT_PUBLIC_VERCEL_ENV)
7. 로컬 개발에서 환경 변수 사용하기#
로컬에서는 프로젝트 최상단의 .env.local 파일에 값을 둡니다.
# .env.local (절대 커밋하지 않음)
WEATHER_API_KEY=<YOUR_API_KEY>
NEXT_PUBLIC_API_URL=http://localhost:3000/api팀원에게는 이름만 적은 .env.example을 커밋해 어떤 변수가 필요한지 알려 줍니다.
# .env.example (커밋함, 값은 비워 둠)
WEATHER_API_KEY=
NEXT_PUBLIC_API_URL=Vercel CLI를 쓰면 Vercel에 저장된 Development 환경 변수를 .env.local로 바로 내려받을 수 있습니다.
vercel env pull자세한 내용은 8장 Vercel CLI를 참고하세요.
.env.local이 .gitignore에 포함되어 있는지 꼭 확인하세요. (1장의 .gitignore 예시 참고)
확인 방법#
문제 해결#
| 증상 | 원인과 해결 |
|---|---|
값이 undefined로 나옴 | 변수 추가 후 재배포하지 않음 → Redeploy |
Production에선 되는데 Preview에선 undefined | Preview 환경에 체크하지 않음 → 변수 편집에서 Preview 선택 |
브라우저 코드에서만 undefined | 노출 접두사 누락 → 공개해도 되는 값이면 NEXT_PUBLIC_ 등 추가 |
| 로컬에선 되는데 Vercel에선 안 됨 | .env.local 값만 있고 Vercel에 등록하지 않음 → 3단계 진행 |
| 변수 이름을 바꿨더니 빌드 실패 | 코드 속 이름과 Vercel 이름의 대소문자·철자 불일치 확인 |
다음 단계#
➡️ 6장. Preview 배포와 PR 흐름: 브랜치와 PR을 이용해 운영 사이트에 영향 없이 변경 사항을 미리 확인합니다.