Vercel: .env가 Git에 없을 때 환경 변수

이 가이드는 이미 Vercel에서 호스팅 중인 프로젝트를 대상으로 합니다. 프로젝트 설정에 접근할 수 있어야 하며 애플리케이션이 어떤 변수를 읽는지 알고 있어야 합니다. 아래 예시는 Next.js에 적용됩니다. 다른 프레임워크의 변수 이름을 자동으로 그대로 사용할 수는 없습니다. 이 가이드는 공식 문서를 바탕으로 작성되었으며 실제 계정에서 테스트하지 않았습니다.

Ailoot 사용에 관한 실용적인 정보는 문서에서 확인할 수 있습니다.

.env를 Git에 추가할 필요가 없는 이유#

환경 변수는 애플리케이션이 소스 코드와 별도로 받는 이름과 값으로 이루어진 설정입니다. 예를 들어 SERVICE_API_KEY라는 이름을 사용하면 프로그램이 외부 서비스 키의 값에 접근할 수 있습니다. 키 자체를 가이드, 에이전트와의 대화 또는 저장소에 넣지 마세요.

Next.js는 로컬 .env* 파일에서 변수를 불러올 수 있습니다. 그러나 로컬 파일과 Vercel 프로젝트 설정은 서로 다른 위치입니다. 파일을 저장소에 푸시하지 않는다면 호스팅 플랫폼에서 값을 별도로 설정하세요. 기본 create-next-app 템플릿은 .env 파일을 .gitignore에 추가합니다. Next.js 문서에서는 해당 파일을 저장소에 푸시하는 일은 거의 없어야 한다고 안내합니다.

소스 파일에 무엇을 저장할 수 있는지 아직 확실하지 않다면 AI로 만든 프로젝트의 보안 점검부터 살펴보세요. 여기서는 범위를 좁혀 특정 Vercel 배포의 설정을 어디에 입력하는지 다룹니다.

먼저 애플리케이션이 변수를 어디서 읽는지 확인하세요#

값을 입력하기 전에 비밀 정보는 제외하고 이름 목록을 작성하세요. 각 이름에 대해 세 가지를 파악해야 합니다. 어떤 환경에서 사용하는지, 변수를 읽는 코드가 어디서 실행되는지, 값이 언제 필요한지입니다.

Development 환경은 로컬 개발용입니다. Preview는 미리 보기 배포용이고, Production은 기본 게시 버전용입니다. Preview에는 특정 Git 브랜치에 적용되는 설정이 있을 수 있습니다. 이러한 설정은 이름이 같은 일반 Preview 설정을 덮어씁니다.

Next.js 프로젝트에서는 NEXT_PUBLIC_가 없는 변수를 기본적으로 서버에서 사용할 수 있습니다. NEXT_PUBLIC_ 접두사를 붙이면 브라우저로 전달되는 JavaScript에 값이 포함됩니다. 비밀이 아닌 버전 라벨처럼 명시적으로 공개해도 되는 설정에는 적합하지만, 비공개 API 키에는 적합하지 않습니다. 이 접두사가 없더라도 애플리케이션 코드는 비밀 정보를 클라이언트에 직접 반환해서는 안 됩니다.

아직 프레임워크를 파악하지 못했다면 에이전트에게 프로젝트 파일을 바탕으로 프레임워크를 식별해 달라고 하세요. Astro와 Next.js 비교를 통해 차이를 이해할 수 있습니다. 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는 해당 위치에서 값을 가져오지 못했다는 뜻입니다. 설정을 한꺼번에 모두 바꾸지 말고 이름, 환경, 버전 순서로 확인하세요.

이름, 환경 및 새 버전을 확인한 뒤에도 함수에서 오류가 발생한다고 해서 변수가 원인이라는 뜻은 아닙니다. 비밀 정보가 포함된 진단 데이터를 공개하지 말고 서버 측 코드에서 발생한 구체적인 오류를 조사하세요. 이 가이드는 모든 HTTP 500 응답을 해결한다고 보장하지 않습니다.

자체 서버로 옮기려면 다른 절차가 필요합니다. Coolify로 프로젝트를 배포하는 가이드를 참조하세요. Vercel의 버튼 이름과 구성 단계는 Coolify에 적용되지 않습니다.

Ailoot로 이동.