문서

환경 변수

배포한 앱에 API 키 같은 값을 넣는 법, 언제 반영되는지, 쓸 수 없는 이름.

환경 변수

배포한 앱이 빌드되고 실행될 때 process.env로 받는 값이에요. API 키나 외부 서비스 주소처럼 저장소에 넣으면 안 되는 값을 여기에 둬요.

list_env_vars    지금 있는 변수. 민감한 값은 뒤 네 자리만
set_env_vars     하나 이상 저장. variables 또는 dotenv(.env 내용 통째로)
remove_env_var   한 곳(production 또는 preview)에서 지우기

어디에 적용되는지

targets로 골라요. production은 프로덕션 브랜치의 배포, preview는 그 밖의 모든 브랜치예요. 같은 이름을 두 곳에 다른 값으로 둘 수 있어요. 프리뷰에는 테스트 키, 프로덕션에는 실제 키. production 값은 소유자·관리자만 바꿀 수 있어요.

언제 반영되는지

바꾼 값은 다음 배포부터 빌드에 쓰여요. 이미 빌드된 결과에 박힌 값은 바뀌지 않아요. 서버로 실행되는 앱은 다음에 시작할 때 새 값을 받아요.

쓸 수 없는 이름

PORT, HOST, HOSTNAME, HOME과 BLACKWALL_로 시작하는 이름은 플랫폼이 써요. 빌드에는 기본으로 CI=1이 들어가고, CI를 직접 정하면(예: CI=false) 그 값을 써요. 플랫폼이 넣어 주는 값:

BLACKWALL_ENV              production 또는 preview
BLACKWALL_URL              이 배포가 서비스되는 주소(호스트 이름)
BLACKWALL_GIT_COMMIT_SHA   빌드한 커밋
BLACKWALL_GIT_BRANCH       빌드한 브랜치

자동으로 들어가는 변수

저장하지 않아도 이 프로젝트의 주소와 키가 Supabase에서 쓰던 이름 그대로 들어가요(list_env_vars의 automatic, 콘솔 환경 변수 화면, oneend env ls). 들어가는 곳(available_in)은 변수마다 달라요.

                                                           들어가는 곳
SUPABASE_URL, NEXT_PUBLIC_SUPABASE_URL                     빌드·실행   https://<ref>.<zone>
SUPABASE_ANON_KEY, NEXT_PUBLIC_SUPABASE_ANON_KEY,
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY                       빌드·실행   공개 키 (접근 규칙을 따름)
SUPABASE_SERVICE_ROLE_KEY                                  실행만      비밀 키 (접근 규칙을 무시, 서버 코드에서만)
DATABASE_URL, POSTGRES_URL                                 운영 실행만  풀러 6543 (비밀번호를 넘길 때만)
DIRECT_URL                                                 운영 실행만  직접 5432 (비밀번호를 넘길 때만)

실행은 서버·미들웨어·함수예요. 서비스 역할 키는 빌드(설치·빌드 명령, 의존 패키지의 스크립트가 도는 곳)에는 들어가지 않아요. 같은 이름으로 저장하면 저장한 값을 쓰고, 저장한 값은 빌드에도 들어가요. 데이터베이스 브랜치가 있는 git 브랜치의 미리보기에는 브랜치의 값이 들어가요. DATABASE_URL·POSTGRES_URL·DIRECT_URL은 reset_database_password { ref, keep_for_deploys: true }(콘솔: 데이터베이스 연결 → 새 비밀번호 만들기 → "운영 배포에 넘기기")로 만든 비밀번호를 보관하는 동안에만 운영 서버·미들웨어·함수에 들어가요(빌드·미리보기 제외). 비밀 키처럼 모든 행을 읽는 연결이에요. keep_for_deploys 없이 다시 만들면 더는 넘기지 않아요. oneend env pull은 공개 값만 .env.local에 써요. Vite 앱은 VITE_SUPABASE_URL처럼 접두사가 다른 이름을 읽으니 직접 저장해야 해요.

민감한 값

sensitive: true로 저장하면 그 뒤로는 값을 다시 읽을 수 없어요. 비밀 키에 쓰세요. sensitive를 주지 않으면 이름에 SECRET, TOKEN, PASSWORD, PRIVATE, DSN, DATABASE_URL, KEY_가 들어가거나 _KEY로 끝나는 변수는 민감한 값으로 저장해요(답의 sensitive_keys). 다시 읽을 수 있게 두려면 sensitive: false를 주세요. 민감하지 않은 값도 모두 암호화해서 저장해요. 차이는 다시 보여 주느냐뿐이에요.

브라우저로 가는 값

NEXT_PUBLIC_·VITE_처럼 프레임워크가 브라우저 코드에 넣는 이름은 빌드 결과에 그대로 들어가 누구나 봐요. 비밀 키에는 이런 이름을 쓰지 마세요.