환경 변수

환경 변수는 코드에 직접 적으면 안 되는 값(API 키, DB 주소 등)을 앱에 넘기는 방법입니다. 나이트로쉽에서는 앱마다 production과 preview 두 가지 대상으로 나눠 저장합니다. 프로덕션 배포는 production 값을, 프리뷰 배포는 preview 값을 씁니다.

아래 명령은 앱에 연결된 폴더에서 실행하거나 --app <앱 이름>을 붙이세요.

추가하고 확인하기제목 링크 복사

ntro env add API_KEY production                    # 비밀 값 (기본)
ntro env add API_ENDPOINT preview --no-sensitive   # 일반 값
ntro env ls

• env add를 실행하면 값을 터미널에서 입력받습니다. 명령줄에 값이 남지 않습니다.
• 기본은 비밀 값(secret)입니다. 저장한 뒤에는 목록에서 가려지고, 다시 꺼내 볼 수 없습니다. 숨길 필요 없는 값이라면 --no-sensitive를 붙이세요.
• 같은 이름·대상이 이미 있으면 오류가 납니다. 덮어쓰려면 --force를 붙이세요.
• CI처럼 질문할 수 없는 환경에서는 대상(production 또는 preview)을 꼭 적어야 합니다.

대시보드에서제목 링크 복사

• 변수를 추가·수정하거나 배포 변수를 입력할 때, 비밀 값은 입력란에 포커스가 있을 때만 보이고 포커스가 벗어나면 다시 가려집니다.
• 환경 변수 표에서는 일반 값은 항상 텍스트로, 비밀 값은 항상 가림 점으로 표시됩니다. 확인할 수 있는 값을 클릭하거나 해당 셀에 포커스를 두고 Enter 또는 Space를 누르면 복사됩니다. 저장된 비밀 값은 가려져 있어 읽거나 복사할 수 없습니다.

플랫폼 변수와 템플릿제목 링크 복사

런타임에는 NITROSHIP=1, NITROSHIP_* 메타데이터(대상, 리전, ID, URL, Git·빌드 정보), PORT가 자동으로 주입됩니다. 알 수 없는 선택적 메타데이터는 빈 문자열입니다. 플랫폼 값은 사용자·이미지 값보다 우선합니다. PORT는 예약 이름이 아니지만 플랫폼 값이 우선합니다. 관리형 Next.js가 HOSTNAME을 서버 bind 주소로 사용하므로 플랫폼은 이 변수를 의도적으로 설정하지 않습니다. 앱 주소에는 NITROSHIP_HOST나 NITROSHIP_URL을 쓰세요.

일반 값(--no-sensitive)에서는 ${NAME}으로 다른 변수를 참조할 수 있습니다.

printf '%s\n' '${NITROSHIP_URL}/api/auth/callback' | ntro env add AUTH_CALLBACK_URL production --no-sensitive

작은따옴표로 감싸면 저장하기 전에 셸이 템플릿을 치환하지 않습니다.

• 참조는 플랫폼 변수와 같은 대상의 사용자 변수만 사용해 재귀적으로 해석합니다. OCI 이미지에만 정의된 변수(PATH 등)는 참조할 수 없습니다.
• 비밀 값은 템플릿이 아닌 리터럴로만 취급하지만, 일반 값에서 비밀 변수를 이름으로 참조할 수 있습니다. 비밀이 포함된 치환 결과가 로그나 클라이언트 응답에 노출되지 않도록 하세요.
• $${는 리터럴 ${로 바뀌고, 중괄호 없는 $NAME은 그대로 둡니다. ${NAME:-fallback} 같은 기본값 문법은 지원하지 않습니다.
• API와 콘솔은 치환 결과가 아닌 원래 일반 값 템플릿을 보여줍니다. 저장한 비밀 값은 계속 숨깁니다.
• 예약 키는 정확히 NITROSHIP, NITROSHIP_ENV, NITROSHIP_REGION, NITROSHIP_INSTANCE_ID, NITROSHIP_DEPLOYMENT_ID, NITROSHIP_APP_ID, NITROSHIP_APP_SLUG, NITROSHIP_TEAM_SLUG, NITROSHIP_HOST, NITROSHIP_URL, NITROSHIP_PRODUCTION_HOST, NITROSHIP_PRODUCTION_URL, NITROSHIP_BRANCH_HOST, NITROSHIP_BRANCH_URL, NITROSHIP_GIT_COMMIT_SHA, NITROSHIP_GIT_BRANCH, NITROSHIP_GIT_REPO, NITROSHIP_BUILD_ID와 NITROSHIP_ISR_·NITROSHIP_PURGE_로 시작하는 모든 이름입니다. 그 밖의 NITROSHIP_* 사용자 키는 허용하지만, 향후 같은 이름의 플랫폼 변수가 추가되면 플랫폼 값이 우선할 수 있으므로 사용을 권장하지 않습니다.
• 저장 시 예약 키, 잘못된 문법, 알 수 없는 참조, 순환 참조를 거부합니다. 같은 대상의 다른 일반 변수가 참조 중인 변수를 삭제하는 것도 거부합니다.

호스티드 빌드에는 플랫폼 메타데이터 중 일부만 제공됩니다. 일반 변수가 런타임 전용 메타데이터(NITROSHIP_URL 등)나 PORT를 직접 또는 재귀적으로 참조하면 그 변수는 빌드 환경에서 제외되고 빌드 로그에 경고가 남습니다. 이 이유로 빌드가 실패하지는 않으며, 런타임에서는 정상 치환합니다.

정확한 런타임·빌드 변수 표와 상세 규칙은 환경 변수 기준 문서를 참고하세요.

내 컴퓨터에서 쓰기제목 링크 복사

ntro env pull                          # 프리뷰 값을 .env.local에 저장
ntro env pull .env.prod --environment production
ntro env run -- npm run dev            # 프리뷰 값을 넣고 명령 실행

• pull은 기본으로 프리뷰의 일반 값만 .env.local에 씁니다. 파일이 이미 있으면 --yes를 붙여야 덮어씁니다.
• run은 파일을 만들지 않고, 값을 넣은 채 -- 뒤의 명령을 실행합니다.
• 비밀 값은 pull·run 어느 쪽으로도 받을 수 없습니다. 로컬에서 필요하다면 따로 관리하세요.

삭제하기제목 링크 복사

ntro env rm API_KEY production

대상을 생략하면 두 대상 모두에서 지웁니다. 삭제 전에 한 번 더 묻습니다.

API 참고제목 링크 복사

REST API의 PUT /v1/apps/{appId}/env는 목록 전체를 교체합니다. 보내지 않은 변수는 지워지므로, 유지할 항목까지 모두 함께 보내세요.