Reporch IDE

환경 변수 연결하기

워크스페이스에 환경 변수를 등록하고 필요한 scope와 target을 선택해 배포에 안전하게 전달합니다.

개요

환경 변수는 워크스페이스 설정에서 먼저 등록하고, 새 배포를 만들 때 사용할 키를 선택합니다. 변수마다 key, value, 적용할 scope/target, 비밀 값 여부를 구분합니다. API 키나 데이터베이스 암호를 코드, MDX 문서 또는 Git 저장소에 저장하지 마세요.

시작하기 전에

애플리케이션이 읽는 정확한 키 이름을 목록으로 만듭니다.
개발·미리보기·프로덕션처럼 값이 달라져야 하는 target을 구분합니다.
브라우저로 전달되는 공개 변수와 서버에서만 읽어야 하는 secret을 구분합니다.
기존 .env.example은 키 이름을 확인하는 용도로만 사용하고 실제 값을 커밋하지 않습니다.

실행 단계

1. 워크스페이스 설정 열기

환경 변수를 사용할 워크스페이스의 설정에서 Environment Variables를 엽니다. 다른 워크스페이스에 같은 이름의 변수가 있어도 자동으로 공유된다고 가정하지 않습니다.

2. key와 value 입력하기

애플리케이션 코드가 읽는 이름과 대소문자까지 정확히 일치하는 key를 입력하고 value를 등록합니다. 앞뒤 공백이나 불필요한 따옴표가 들어가지 않았는지 확인합니다.

3. secret 여부와 범위 정하기

노출되면 안 되는 값은 secret으로 표시합니다. 제공되는 scope와 target 중 실제로 필요한 환경만 선택해 접근 범위를 최소화합니다.

4. 새 배포 열기

배포 → 새 배포로 이동하고 Environment Variables 영역을 펼칩니다. 등록한 key, scope와 target이 예상대로 표시되는지 확인합니다.

5. 필요한 변수만 선택하기

이번 애플리케이션이 실제로 사용하는 항목만 체크합니다. 이름이 비슷한 개발용·프로덕션용 값을 혼동하지 않도록 target을 다시 확인합니다.

6. 배포 후 동작 확인하기

배포를 실행하고 누락된 변수 오류가 없는지 로그를 확인합니다. 로그나 오류 메시지에 비밀 값 자체를 출력하는 디버그 코드는 제거합니다.

이름과 값 작성 원칙

환경 변수 이름은 대소문자를 구분합니다. DATABASE_URL과 database_url은 다른 키입니다.
값에 줄바꿈이 필요한 인증서나 개인 키는 제공되는 입력 형식을 그대로 사용하고 임의로 \n을 추가하지 않습니다.
NEXT_PUBLIC_, VITE_처럼 프레임워크가 클라이언트 번들에 포함하는 접두사는 비밀 값에 사용하지 않습니다.
값을 교체한 뒤에는 기존 배포가 자동으로 바뀐다고 가정하지 말고 새 배포가 필요한지 확인합니다.

예상 결과

선택한 변수만 새 배포의 실행 환경에 전달됩니다.
애플리케이션은 코드에 값을 하드코딩하지 않고 동일한 key로 환경별 값을 읽습니다.
비밀 값은 문서, 저장소와 일반 로그에 나타나지 않습니다.

문제 해결

목록이 비어 있음: 현재 워크스페이스 설정에 변수를 먼저 등록했는지 확인합니다.
undefined 또는 missing 오류: key의 철자·대소문자, 선택 여부와 target을 확인합니다.
개발에서는 되고 배포에서 실패함: 로컬 .env에만 있고 배포에는 선택하지 않은 값이 있는지 비교합니다.
값을 바꿨는데 이전 값이 사용됨: 변수 변경 시점 이후 새 배포를 만들고 해당 배포의 Deployment ID를 확인합니다.
비밀 값이 로그에 보임: 즉시 값을 폐기·재발급하고 애플리케이션의 로그 출력을 수정합니다.