환경 변수

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

환경 변수가 저장되는 위치

Orbit에서 프로젝트를 열고 /orbit/<project-id>/env-vars의 Env vars 탭을 클릭하십시오.

페이지는 다음과 같이 구성됩니다:

모든 환경: 맨 위에 있으며, 프로젝트 전체 변수로 모든 빌드에서 사용 가능합니다.
환경별 축소 가능 섹션(Production, Staging 및 모든 미리보기): 해당 환경의 재정의를 보유합니다.

목록 위에는 검색 상자와 Secrets only 필터가 있으며, 이는 긴 목록을 빠르게 탐색하는 방법입니다.

범위의 작동 방식

범위	영향 범위
모든 환경(프로젝트 전체)	이 프로젝트의 모든 빌드에 주입됨
환경 수준 재정의	해당 환경에만 적용되며, 같은 키의 프로젝트 전체 값을 무시함

페이지의 부제목은 규칙을 명확하게 설명합니다: 프로젝트 전체 변수는 모든 빌드에서 사용 가능하며, 환경 수준 재정의가 우선순위를 갖습니다.

일반적인 설정은 테스트 데이터베이스를 가리키는 프로젝트 전체 DATABASE_URL이고, 프로덕션 수준 재정의가 실제 데이터베이스를 가리킵니다. 프로덕션 빌드는 실제 데이터베이스를 얻고, 다른 모든 것은 테스트 데이터베이스를 얻으며, 나중에 추가하는 어떤 것도 프로덕션 자격 증명을 미리보기에 실수로 유출하지 않습니다.

또한 프로젝트 전체 변수에 Available in 컨트롤이 있으므로, 특정 환경 유형(production, staging, preview)을 제외할 수 있습니다.

환경별 범위 지정에 대한 전체 세부사항(보안 이유 포함)은 환경별로 환경 변수 설정을 참조하십시오.

프로젝트 전체 변수는 분기 미리보기 빌드에 주입되며, 미리보기 URL은 링크를 가진 누구나 공개적으로 접근할 수 있습니다. 프로덕션 데이터베이스 자격 증명, 실제 결제 키 및 관리자 토큰은 프로덕션에만 범위를 지정해야 합니다. 이것이 이 페이지에서 올바르게 처리해야 할 가장 중요한 사항입니다.

변수 추가

Env vars 탭 맨 아래의 Add variable 양식으로 스크롤합니다.
KEY를 입력합니다(예: NEXT_PUBLIC_API_URL).
value를 입력합니다.
Scope을 선택합니다: All environments (project-wide) 또는 특정 환경 재정의.
프로젝트 전체를 선택한 경우, Available in 버튼을 사용하여 이 변수가 도달하면 안 되는 모든 환경 유형을 선택 해제합니다.
민감한 내용의 경우 Mark as secret을 선택합니다.
Add를 클릭합니다.

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

변경 사항이 적용되는 시점

변수를 추가, 편집 또는 삭제해도 현재 라이브 상태인 배포는 변경되지 않습니다. 변수는 빌드가 실행될 때 주입되므로, 변경 사항은 다음 배포부터 적용됩니다. 앱이 의존하는 항목을 변경한 후 재배포하십시오.

Orbit은 이에 대해 명확합니다. 배포의 세부사항 페이지를 열고, 빌드된 이후로 구성이 변경된 경우, Environment variables updated since this deployment 공지가 표시되어 재배포할 때까지 변경 사항이 적용되지 않음을 알려줍니다.

비밀

채팅에 붙여넣기하지 않을 모든 항목에 대해 Mark as secret을 선택합니다: API 키, 데이터베이스 암호, 토큰, 서명 키.

비밀 값은 패널에서 마스킹되고 secret 배지를 표시합니다. 비밀이 아닌 값은 (plain) 표시자를 표시합니다.

비밀의 값은 저장된 후 다시 읽을 수 없습니다. 패널에서 누구도 읽을 수 없습니다. 편집할 수 있지만(편집 아이콘을 클릭하고 새 값을 입력하고 저장), 공개할 수는 없습니다. 여기에 저장하기 전에 암호 관리자에 자신의 복사본을 유지하십시오.

Orbit은 또한 값이 제자리에 있던 시간을 추적하고 더 오래된 변수에 age 배지를 표시하며, 회전을 제안하는 힌트가 있습니다. 이는 권장 사항이지 강제 사항이 아닙니다.

편집 및 삭제

변수 옆의 편집 아이콘을 클릭하여 값을 변경합니다. Delete를 클릭하여 제거하고 확인합니다: 대화 상자는 이에 따라 빌드가 중단됨을 경고하며, 이는 다음 배포에서 발생할 상황의 정확한 설명입니다.

대량 가져오기 및 내보내기

탭 맨 위의 두 버튼이 대량 작업을 처리합니다.

Import .env는 붙여넣기 상자를 엽니다. .env 파일의 내용을 붙여넣고, 범위를 선택하면 Orbit은 감지된 변수 수와 비밀로 표시할 변수 수를 알려줍니다. 이름을 기반으로 키를 자동으로 플래그하므로, SECRET, TOKEN, KEY, PASSWORD 및 유사한 내용을 포함하는 모든 것은 가져오기 전에 비밀로 표시됩니다. Overwrite existing variables with the same key 옵션이 있으며, 기본값은 해제되어 있습니다.

Download .env는 값이 없는 변수 이름만 포함하는 템플릿을 생성합니다. 이는 백업으로 사용되지 않고 팀원과 공유하기 위해 고안되었으며, 팀원은 자신의 값을 입력합니다.

.env 템플릿을 다운로드하면 비밀이 아닌 변수를 포함한 값을 포함하지 않습니다. Orbit에서 값을 내보낼 수 있는 방법이 없습니다. 값의 복사본이 필요한 경우 원래 생성한 위치에서 가져가십시오.

환경 간 변수 복사

Copy variables between environments 패널은 한 범위에서 다른 범위로 전체 집합을 복사합니다. From(프로젝트 수준 또는 특정 환경)과 To를 선택하고, 선택적으로 Overwrite variables that already exist in the target을 선택하고, Preview를 클릭하여 커밋하기 전에 추가, 업데이트 및 건너뛸 정확한 수를 확인합니다.

또한 Env sync check 페이지가 있으며, 프로덕션과 스테이징을 키별로 비교하고 한쪽에만 있는 것, 다른 것 및 일치하는 것을 보고합니다. 이는 "왜 스테이징은 작동하고 프로덕션은 작동하지 않는가"에 대한 올바른 도구입니다.

프로젝트 간 변수 공유

여러 프로젝트에 동일한 자격 증명이 필요한 경우, 각 프로젝트에 복사하는 대신 env group을 사용합니다. Orbit으로 이동한 다음, Env groups으로 이동하여 그룹을 만들고, 변수를 추가하고, 필요한 프로젝트를 연결합니다.

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

프레임워크 참고사항

어떤 변수가 브라우저에 도달하는지는 Orbit이 아닌 프레임워크에 의해 결정됩니다. Orbit은 범위 내의 모든 것을 주입하고, 프레임워크가 노출할 항목을 결정합니다.

Next.js: NEXT_PUBLIC_ 접두사가 있는 키는 빌드 시 브라우저 번들에 인라인됩니다. 다른 모든 것은 서버 쪽에 유지됩니다.
Vite: VITE_ 접두사가 있는 키는 브라우저에 노출됩니다. 다른 모든 것은 빌드 시간 전용입니다.
Node.js 앱: 범위 내의 모든 것은 빌드 중 process.env에 있으며, Server mode가 켜져 있을 때 런타임에 있습니다.

값을 비밀로 표시한 다음 NEXT_PUBLIC_ 또는 VITE_도 접두사하지 마십시오. 비밀 플래그는 패널이 값을 표시하는지 여부만 제어하고, 접두사는 프레임워크가 모든 방문자의 브라우저로 배송하는지 여부를 제어합니다. 접두사가 우선합니다.

빌드가 실제로 수신한 항목 확인

모든 배포 세부사항 페이지는 빌드 시간에 주입된 환경 변수 키를 나열하고, 현재 구성과 비교합니다: 추가, 변경, 제거 및 변경 없음. 녹청색 키는 환경별 재정의에서 나오고, 회색 키는 프로젝트 수준에서 나옵니다. 값은 저장되거나 표시되지 않지만, 키를 가리키면 SHA-256 지문이 제공되며, 이는 두 환경이 값을 공개하지 않고 동일한 값을 보유하고 있음을 확인하기에 충분합니다.

이것은 "내 변수가 실제로 빌드에 도달하고 있는가"에 대한 최종적인 답입니다. 다른 항목을 변경하기 전에 이를 확인하십시오.

문제 해결

변수가 런타임에 정의되지 않았습니다. 배포가 변경 이후인지 확인한 다음, 범위가 이 환경을 포함하는지 확인하고, 위의 프레임워크 접두사 규칙을 확인하십시오. 그 순서대로 수행하십시오.

프로덕션에서는 작동하지만 미리보기에서는 작동하지 않습니다. 변수의 범위가 프로덕션만으로 지정되거나, 프로젝트 전체 변수에 Available in에서 preview이 선택 해제되어 있습니다. 이는 보통 의도적입니다.

로컬에서는 작동하지만 빌드에서는 작동하지 않습니다. 로컬 .env 파일이 저장소에 없으며 있으면 안 됩니다. Import .env로 가져오고 올바른 범위를 선택하십시오.

스테이징에 프로덕션이 가지고 있는 모든 항목이 없습니다. Settings에서 Inherit production env vars를 켜십시오, Staging: environment variables 아래에서, 또는 Copy variables between environments를 사용하십시오.