# Vercel: .env가 Git에 없을 때 환경 변수
> 환경 변수, Development/Preview/Production, 새 배포, 브라우저에 비밀 키를 전달하지 않고 Next.js에서 안전하게 확인하는 방법.
Source: https://ailoot.ai/blog/ko/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/ko/vercel-environment-variables/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-ac40f941c77fd487b034b1a850ffc0fcc740063da9442067b2b2c779d49d20e9
핵심 요점
비밀 정보가 들어 있는 `.env` 파일이 Git에 없다면 Vercel 프로젝트의 **Environment Variables** 섹션에 필요한 변수를 추가하세요. 환경을 선택하고 설정을 저장한 다음 새 배포를 만드세요. 이미 배포된 버전은 변경되지 않습니다. Next.js에서는 비밀 키에 `NEXT_PUBLIC_` 접두사를 추가하지 마세요. 빌드 중에 해당 값이 브라우저 코드에 포함됩니다.
이 가이드는 이미 Vercel에서 호스팅 중인 프로젝트를 대상으로 합니다. 프로젝트 설정에 접근할 수 있어야 하며 애플리케이션이 어떤 변수를 읽는지 알고 있어야 합니다. 아래 예시는 Next.js에 적용됩니다. 다른 프레임워크의 변수 이름을 자동으로 그대로 사용할 수는 없습니다. 이 가이드는 공식 문서를 바탕으로 작성되었으며 실제 계정에서 테스트하지 않았습니다.
[Ailoot 사용에 관한 실용적인 정보는 문서에서 확인할 수 있습니다](https://ailoot.ai/docs/).
## .env를 Git에 추가할 필요가 없는 이유
환경 변수는 애플리케이션이 소스 코드와 별도로 받는 이름과 값으로 이루어진 설정입니다. 예를 들어 `SERVICE_API_KEY`라는 이름을 사용하면 프로그램이 외부 서비스 키의 값에 접근할 수 있습니다. 키 자체를 가이드, 에이전트와의 대화 또는 저장소에 넣지 마세요.
Next.js는 로컬 `.env*` 파일에서 변수를 불러올 수 있습니다. 그러나 로컬 파일과 Vercel 프로젝트 설정은 서로 다른 위치입니다. 파일을 저장소에 푸시하지 않는다면 호스팅 플랫폼에서 값을 별도로 설정하세요. 기본 `create-next-app` 템플릿은 `.env` 파일을 `.gitignore`에 추가합니다. Next.js 문서에서는 해당 파일을 저장소에 푸시하는 일은 거의 없어야 한다고 안내합니다.
소스 파일에 무엇을 저장할 수 있는지 아직 확실하지 않다면 [AI로 만든 프로젝트의 보안 점검](https://ailoot.ai/blog/ko/vibe-coding-security/)부터 살펴보세요. 여기서는 범위를 좁혀 특정 Vercel 배포의 설정을 어디에 입력하는지 다룹니다.
## 먼저 애플리케이션이 변수를 어디서 읽는지 확인하세요
값을 입력하기 전에 비밀 정보는 제외하고 **이름** 목록을 작성하세요. 각 이름에 대해 세 가지를 파악해야 합니다. 어떤 환경에서 사용하는지, 변수를 읽는 코드가 어디서 실행되는지, 값이 언제 필요한지입니다.
| 확인할 항목 | 가능한 옵션 | 중요한 이유 |
|----|----|----|
| Vercel 환경 | Development, Preview, Production | 설정이 확인하려는 버전에 적용되어야 합니다 |
| 변수를 읽는 위치 | 서버 또는 브라우저 | 비공개 키가 클라이언트 측 코드에 포함되어서는 안 됩니다 |
| 변수를 읽는 시점 | 빌드 시간 또는 서버 함수 실행 시 | Next.js에서는 공개 값이 빌드 중에 고정됩니다 |
**Development** 환경은 로컬 개발용입니다. **Preview**는 미리 보기 배포용이고, **Production**은 기본 게시 버전용입니다. Preview에는 특정 Git 브랜치에 적용되는 설정이 있을 수 있습니다. 이러한 설정은 이름이 같은 일반 Preview 설정을 덮어씁니다.
Next.js 프로젝트에서는 `NEXT_PUBLIC_`가 없는 변수를 기본적으로 서버에서 사용할 수 있습니다. `NEXT_PUBLIC_` 접두사를 붙이면 브라우저로 전달되는 JavaScript에 값이 포함됩니다. 비밀이 아닌 버전 라벨처럼 명시적으로 공개해도 되는 설정에는 적합하지만, 비공개 API 키에는 적합하지 않습니다. 이 접두사가 없더라도 애플리케이션 코드는 비밀 정보를 클라이언트에 직접 반환해서는 안 됩니다.
아직 프레임워크를 파악하지 못했다면 에이전트에게 프로젝트 파일을 바탕으로 프레임워크를 식별해 달라고 하세요. [Astro와 Next.js 비교](https://ailoot.ai/blog/ko/astro-vs-nextjs-for-ai-built-sites/)를 통해 차이를 이해할 수 있습니다. `NEXT_PUBLIC_` 규칙을 모든 React 애플리케이션에 적용할 수는 없습니다.
호스팅 설정은 AI 에이전트와 애플리케이션을 작업할 때 수행하는 여러 작업 중 하나입니다.
## Vercel 프로젝트에 변수를 추가하는 방법
공식 대시보드에서 직접 단계를 수행하세요. 실제 키를 에이전트에게 주어 양식에 입력하게 하지 말고, 값이 보이는 스크린샷도 첨부하지 마세요.
1. Vercel 대시보드를 열고 **올바른 프로젝트**를 선택하세요. 저장소 이름이 일치하는지만 믿지 말고, 열려는 애플리케이션을 설정하고 있는지 확인하세요.
2. 프로젝트 설정 사이드바에서 **Environment Variables**로 이동하세요.
3. **Name**에 애플리케이션이 읽는 이름을 입력하세요. 예: `SERVICE_API_KEY`. 이는 예시 이름입니다. 코드에서 다른 이름을 요구한다면 철자를 정확히 맞춰 입력하세요.
4. **Value**에 자격 증명 보관소의 값을 입력하세요. 소스 코드, 채팅 또는 확인 로그에 넣지 마세요.
5. 이 설정이 필요한 환경을 선택하세요. 미리 보기 버전을 확인하려면 **Preview**, 기본 버전에는 **Production**을 사용하세요. 하나의 비밀 정보를 모든 환경에 자동으로 할당하지 마세요.
6. Preview 설정이 특정 브랜치에 적용된다면 선택된 브랜치와 같은 이름의 덮어쓰기 설정이 있는지 확인하세요.
7. **Save**를 클릭하세요.
Vercel은 프로젝트 변수를 빌드 중과 서버 측 Vercel Functions 실행 중에 모두 사용할 수 있게 합니다. 그러나 Vercel 내부에서 값을 사용할 수 있다고 해서 브라우저로 전송해도 된다는 뜻은 아닙니다. 이는 애플리케이션 코드와 프레임워크의 규칙에 따라 달라집니다.
## Save 후 새 배포가 필요한 이유
변수를 저장해도 기존 배포는 변경되지 않습니다. Vercel 문서에 따르면 새 설정을 사용하는 버전에 반영하려면 프로젝트를 다시 배포해야 합니다.
Git을 사용하는 경우 **Production Branch**에 지정된 브랜치에 커밋을 푸시하면 새 Production 배포를 만들 수 있고, 다른 브랜치에 푸시하면 Preview 배포를 만들 수 있습니다. 기본 브랜치가 항상 `main`이라고 가정하지 말고 프로젝트 설정을 확인하세요. 비밀 파일을 커밋에 추가하지 말고, 평소처럼 합의된 프로젝트 릴리스를 진행해야 합니다.
배포를 시작한 뒤 빌드가 완료될 때까지 기다리고 **새** 배포의 URL을 여세요. 해당 URL, 환경 및 브랜치를 기록해 두세요. 개별 배포의 이전 URL을 확인하면 새 설정이 표시되지 않습니다.
Next.js에는 또 다른 조건이 있습니다. `process.env.NEXT_PUBLIC_RELEASE_LABEL` 같은 참조는 `next build` 중에 실제 값으로 대체됩니다. 값은 빌드가 끝난 뒤 고정됩니다. 새 빌드 없이 설정을 바꾸면 이미 전달된 클라이언트 측 JavaScript는 다시 작성되지 않습니다.
## 키를 노출하지 않고 결과를 확인하는 방법
먼저 명시적으로 비밀이 아닌 `NEXT_PUBLIC_RELEASE_LABEL`이라는 라벨을 `preview-check` 값으로 설정해 안전하게 확인하세요. 이는 이름과 텍스트의 예시일 뿐, 키가 아니며 여기서 수행한 테스트도 아닙니다. Next.js 애플리케이션이 `process.env.NEXT_PUBLIC_RELEASE_LABEL`을 통해 이 변수를 직접 읽는다면 새 빌드 후 인터페이스의 의도한 위치에 라벨을 표시할 수 있습니다. 이 확인으로는 공개 설정이 전달되었는지만 확인할 수 있습니다.
**비공개 키는 다른 방식으로 확인해야 합니다.** 키의 값이나 일부, 길이 또는 전체 `process.env`를 출력하지 마세요. 변수 내용을 반환하는 공개 URL을 만들지 마세요. 먼저 서버에서 설정이 “있음 / 없음”인지 여부만 확인하고, 그다음 해당 서비스를 사용하는 애플리케이션 함수를 별도로 확인하세요. 설정이 존재한다고 해서 키가 유효하거나 필요한 권한을 갖췄다는 뜻은 아닙니다.
비밀 정보를 포함하지 않고 결과를 기록할 수 있습니다.
- 프로젝트, 환경 및 브랜치가 설정 중 선택한 항목과 일치합니다.
- 변수를 저장한 후 생성된 새 배포의 URL을 확인하고 있습니다.
- 빌드가 완료되었으며 필요한 애플리케이션 함수가 안전한 테스트 데이터로 실행되었습니다.
- 브라우저, API 응답, 로그 또는 대화에 비밀 정보가 노출되지 않았습니다.
함수가 결제를 하거나 메시지를 보내는 등 결과를 초래하는 작업을 수행한다면 서비스에서 지정한 테스트 모드를 사용하세요. 설정을 확인했다고 해서 실제 작업이 자동으로 승인되는 것은 아닙니다.
## 값이 계속 undefined인 경우 확인할 사항
`undefined`는 해당 위치에서 값을 가져오지 못했다는 뜻입니다. 설정을 한꺼번에 모두 바꾸지 말고 이름, 환경, 버전 순서로 확인하세요.
| 증상 | 확인할 사항 |
|----|----|
| 로컬에서는 작동하지만 Preview에서는 작동하지 않음 | 프로젝트의 Preview 설정에 이름이 있는지, 다른 브랜치를 선택했는지 확인 |
| Preview에서는 작동하지만 Production에서는 작동하지 않음 | Production에 이름이 설정되어 있는지, Save 후 새 기본 버전을 만들었는지 확인 |
| 한 Preview 브랜치에서만 다르게 동작함 | 같은 이름의 값이 해당 브랜치에 설정되어 일반 설정을 덮어쓰는지 확인 |
| 서버에서는 변수가 보이지만 브라우저에서는 보이지 않음 | Next.js에서 공개되지 않은 변수라면 예상된 동작입니다. 비공개 키를 브라우저로 옮기지 마세요 |
| 공개 Next.js 라벨에 여전히 이전 값이 표시됨 | 필요한 값으로 새 빌드를 했는지, 연 URL이 해당 배포에 속하는지 확인 |
| 공개 이름은 올바르지만 대체가 작동하지 않음 | 코드가 `process.env[varName]`으로 동적으로 읽는지 확인하세요. Next.js는 이런 참조를 인라인하지 않습니다 |
이름, 환경 및 새 버전을 확인한 뒤에도 함수에서 오류가 발생한다고 해서 변수가 원인이라는 뜻은 아닙니다. 비밀 정보가 포함된 진단 데이터를 공개하지 말고 서버 측 코드에서 발생한 구체적인 오류를 조사하세요. 이 가이드는 모든 HTTP 500 응답을 해결한다고 보장하지 않습니다.
자체 서버로 옮기려면 다른 절차가 필요합니다. [Coolify로 프로젝트를 배포하는 가이드](https://ailoot.ai/blog/ko/coolify-claude-code-deploy/)를 참조하세요. Vercel의 버튼 이름과 구성 단계는 Coolify에 적용되지 않습니다.
### 출처
- [Vercel 환경 변수](https://vercel.com/docs/environment-variables)
- [Vercel 환경 변수 추가 및 관리](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Next.js 환경 변수](https://nextjs.org/docs/app/guides/environment-variables)
[Ailoot로 이동](https://ailoot.ai/).
## Vercel: .env가 Git에 없을 때 환경 변수: 자주 묻는 질문
### Vercel에 변수를 저장했는데도 undefined인 이유는 무엇인가요?
프로젝트, 환경, 브랜치별 적용 범위를 확인한 뒤 새 배포를 만드세요. 새 설정을 저장하는 것만으로 기존 배포에 변수가 생기지는 않습니다.
### Next.js 앱에서 비밀 값을 읽도록 NEXT_PUBLIC_을 붙여도 되나요?
비밀 정보에는 그 접두사를 쓰지 마세요. 빌드 중 값이 브라우저 코드에 들어갑니다. 서버에 유지하고 키를 출력하지 않는 방식으로 존재 여부를 확인하세요.
## Ailoot · 회사와 그 프로젝트 포트폴리오
Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.
회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.
Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.