환경별 환경 변수 설정

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…

Orbit를 사용하면 어느 빌드가 어느 환경 변수를 볼지 정확히 결정할 수 있으므로, 프로덕션 자격증명이 공개적으로 접근 가능한 브랜치 미리보기에 포함되지 않습니다. 이 가이드는 스코프와 우선순위 작동 방식, 프로덕션 전용 변수를 추가하는 방법, 스테이징 상속 동작 방식, 그리고 빌드가 실제로 받은 내용을 검증하는 방법을 다룹니다.

이것이 중요한 이유

브랜치 미리보기는 공개 URL을 받습니다. 링크를 가진 누구나 로드할 수 있습니다. 변수가 모든 환경으로 스코프되어 있으면, 해당 미리보기의 빌드에 주입되고, 미리보기가 그것으로 무엇을 하든 프로덕션 자격증명으로 합니다.

이것이 이 페이지가 존재하는 전체 이유입니다. 아래의 모든 내용은 한 가지 규칙을 위한 것입니다: 프로덕션 시크릿은 프로덕션 스코프에만 속하고, 다른 곳에는 속하지 않습니다.

스코핑 작동 방식

모든 변수는 빌드 시 언제 주입될지를 결정하는 스코프를 가집니다.

스코프	주입 대상
모든 환경(프로젝트 전체)	제한하지 않는 한 이 프로젝트의 모든 빌드
특정 환경 재정의	해당 환경 하나만의 빌드

동일한 키가 두 수준에 모두 존재할 때, 더 구체적인 것이 우선입니다. 환경 수준의 재정의는 동일한 키의 프로젝트 전체 변수를 이깁니다. Env vars 페이지는 "모든 환경" 섹션의 부제목에서 이를 명시합니다: 프로젝트 전체 변수는 모든 빌드에서 사용 가능하며, 환경 수준 재정의가 우선합니다.

프로젝트 전체 변수는 재정의가 되지 않으면서도 좁혀질 수 있습니다. 사용 가능한 환경 컨트롤은 세 가지 환경 유형(production, staging, preview)을 제공하며 이들 중 아무것이든 선택 해제할 수 있습니다.

스코프를 사용하여 변수 추가

Orbit에서 프로젝트를 열고 Env vars 탭을 클릭합니다.
하단의 변수 추가 양식으로 스크롤합니다.
KEY와 값을 입력합니다.
스코프 드롭다운을 사용합니다:
- **모든 환경(프로젝트 전체)**은 모든 빌드에 주입합니다.
- **[환경 이름] 전용([유형] 재정의)**은 해당 환경 하나로만 스코프합니다.
프로젝트 전체를 선택한 경우, 사용 가능한 환경 버튼을 사용하여 이 변수가 도달하지 않아야 할 환경 유형을 선택 해제합니다.
민감한 항목에 대해 시크릿으로 표시를 선택합니다.
추가를 클릭합니다.

커밋하기 전에, 양식이 수행할 작업을 알려줍니다. 재정의는 해당 환경의 빌드에만 적용되고 프로젝트 전체 변수는 다른 곳에서도 적용된다는 공지를 표시합니다. 제한된 프로젝트 전체 변수는 주입될 환경 유형을 정확히 표시합니다.

프로덕션 전용 변수 추가

두 가지 동등한 경로:

스코프 드롭다운에서 프로덕션 환경을 선택합니다(녹색 production 배지를 포함), 또는
스코프를 모든 환경으로 유지하고 사용 가능한 환경에서 staging와 preview를 선택 해제합니다.

어느 쪽이든, 미리보기나 스테이징 빌드가 실행될 때 변수는 없습니다.

"없음"은 없음을 의미하며, 비어 있음이 아닙니다. 미리보기 빌드에서 process.env.STRIPE_SECRET_KEY을 읽는 코드는 undefined을 받으며, 작성 방식에 따라 빌드 시 throw되거나, 더 나쁘게는 조용히 잘못된 분기를 선택할 수 있습니다. 미리보기에 값이 없는 것보다는 테스트 모드 값을 제공합니다.

안전 패턴

대부분의 프로젝트에서 이를 깔끔하게 해결하는 패턴:

프로덕션 자격증명을 프로덕션 환경에만 스코프되도록 추가합니다.
동일한 키를 보유한 변수를 테스트 또는 샌드박스 값으로 프로젝트 전체 스코프에 추가합니다.

프로덕션 빌드는 더 구체적인 스코프가 우선이므로 프로덕션 스코프된 값을 받습니다. 미리보기 및 스테이징은 테스트 값을 받습니다. 어디에도 정의되지 않은 것이 없으며, 프로덕션 자격증명은 절대 미리보기에 도달하지 않습니다.

다음에 적용합니다:

프로덕션 데이터베이스 URL
결제 제공자 시크릿 키(미리보기에는 제공자의 테스트 키 사용)
이메일 전송 키(미리보기가 실제 고객에게 메일을 보낼 수 없도록)
관리자 토큰 및 서명 시크릿
호출당 비용이 있는 모든 것

스테이징에서 프로덕션 변수 상속

스테이징 환경이 프로덕션에 가깝고 몇 가지 값만 재정의하려면, 모든 것을 복제할 필요가 없습니다.

설정에서 스테이징: 환경 변수를 찾아 프로덕션 env vars 상속을 켭니다. 프로덕션 변수는 스테이징 특정 재정의보다 낮은 우선순위로 스테이징 빌드에 병합되므로, 스테이징에서 명시적으로 설정한 모든 것이 여전히 우선합니다.

상속은 프로덕션 자격증명을 포함하여 프로덕션 값을 스테이징 빌드에 복사합니다. 스테이징 환경이 보호되는 경우에만 켭니다. 스테이징은 설정의 스테이징: 액세스 보호 및 스테이징: IP 허용 목록 섹션에서 비밀번호와 IP 허용 목록을 모두 지원합니다. 보호되지 않은 스테이징 환경에 상속을 켜면 이 페이지가 다루는 정확히 동일한 노출을 다시 만듭니다.

기존 변수 보기 및 편집

Env vars 탭은 변수를 다음과 같이 그룹화합니다:

맨 위의 모든 환경, 프로젝트 전체 변수 포함
환경별 축소 가능 섹션, 해당 환경의 재정의 포함(개수 표시)

그 위에 검색 상자와 시크릿만 필터가 있습니다.

각 변수 이름 옆의 배지는 어느 환경 유형에 도달하는지 표시합니다. production과 preview를 표시하지만 staging은 아닌 변수는 스테이징 빌드에서 누락되며, 이 배지 행은 긴 목록을 감시하는 가장 빠른 방법입니다.

편집 아이콘을 클릭하여 값을 변경합니다. 시크릿 변수의 현재 값은 표시할 수 없으며, 대체만 가능합니다.

환경 간 복사 및 비교

환경 간 변수 복사는 한 스코프에서 다른 스코프로 전체 집합을 복사합니다. 출처와 대상을 선택하고, 선택적으로 대상에 이미 존재하는 변수 덮어쓰기를 선택한 후 미리보기를 클릭하여 커밋하기 전에 추가, 업데이트 및 건너뛸 개수를 확인합니다.

Env sync check 페이지는 프로덕션과 스테이징을 키별로 비교하고 하나에만 존재하는 것, 다른 값을 가진 것, 일치하는 것을 보고합니다. 이것이 "스테이징은 작동하고 프로덕션은 작동하지 않거나" 그 반대일 때 올바른 첫 번째 정류장입니다.

프로덕션과 스테이징 간의 값 차이는 대부분의 시크릿에서 정상이고 예상됩니다. sync 페이지가 그렇게 말합니다. 찾고 있는 것은 한 환경에 있고 다른 환경에 없는 키입니다.

프로젝트 간 변수 공유

여러 프로젝트가 동일한 자격증명이 필요한 경우, 각 프로젝트에 붙여넣기보다는 env 그룹을 사용합니다. Orbit으로 이동한 후 Env groups, 그룹을 생성하고, 변수를 추가한 후, 그것을 필요로 하는 프로젝트를 연결합니다.

그룹 변수는 빌드 시 주입되며 우선순위 순서의 하단에 있습니다: 프로젝트 수준 및 환경 수준 변수 모두 그룹 변수보다 우선합니다. 계정에 최대 20개의 그룹을 가질 수 있습니다.

그룹을 삭제하면 모든 연결된 프로젝트의 향후 빌드에서 해당 변수가 제거됩니다. 이미 완료된 빌드는 영향을 받지 않습니다.

대량 가져오기

Import .env 버튼은 붙여넣기 상자를 엽니다. .env 파일을 붙여넣고, 스코프를 선택하면, Orbit은 찾은 변수의 개수와 시크릿으로 표시할 개수를 보고합니다. SECRET, TOKEN, KEY, PASSWORD 및 유사 용어를 포함하는 키는 자동으로 플래그됩니다. 동일한 키의 기존 변수 덮어쓰기 옵션이 있으며, 기본값은 꺼져 있습니다.

Download .env는 변수 이름만 포함하는 템플릿을 생성하며, 자신의 값을 제공할 동료와 공유할 값은 없습니다.

Import를 클릭한 후가 아니라 가져오기 대화상자에서 스코프를 선택합니다. 전체 프로덕션 .env을 프로젝트 전체 스코프에서 가져오면 모든 프로덕션 자격증명이 한 번의 작업으로 미리보기 빌드에 푸시되며, 해결책은 설정을 변경하는 것이 아니라 다시 삭제하고 추가하는 것입니다.

빌드가 실제로 받은 내용 검증

모든 배포의 상세 페이지는 빌드 시 주입된 환경 변수 키를 나열하고 현재 구성과 대비합니다: 추가됨, 변경됨, 제거됨, 변경 없음. 청록색 키는 환경 특정 재정의에서, 회색 키는 프로젝트 수준에서 나온 것입니다.

값은 절대 저장되거나 표시되지 않습니다. 키에 마우스를 올리면 SHA-256 지문이 제공되므로, 값을 노출하지 않으면서도 두 환경이 동일한 값을 보유하고 있는지 확인하기에 충분합니다.

해당 배포가 빌드된 후 구성이 변경된 경우, 페이지는 이 배포 이후 환경 변수 업데이트됨 공지와 함께 이를 표시하고, 변경이 다시 배포할 때까지 적용되지 않는다는 것을 상기시킵니다.

변수 변경은 이미 실행 중인 배포에 적용되지 않습니다. 빌드가 실행될 때 주입됩니다. 앱이 의존하는 것을 변경한 후에는 다시 배포합니다.