프로덕션 환경 변수의 빌드·실행 시점

공개 변수와 서버 변수는 굳는 시간이 달라

변수	읽는 시점
`NEXT_PUBLIC_*`	빌드 시점에 클라이언트 번들에 값이 들어가.
서버 전용 변수	실행 시점에 서버가 요청마다 읽을 수 있어.

Docker 이미지 하나로 공개 설정을 바꿀 수 없어

한 이미지를 staging과 production에 배포해도 NEXT_PUBLIC_* 값은 이미 빌드 결과에 박혀 있어. 컨테이너를 실행할 때 다른 환경 변수를 넣어도 브라우저 번들은 변하지 않아. 환경마다 빌드하거나, 서버가 실행 시점 값을 읽어 안전한 공개 설정만 내려 주는 방식을 따로 설계해.

환경 파일 우선순위를 알아 둬

이미 설정된 process.env
.env.production.local 또는 .env.development.local
.env.local, 단 test에서는 제외
.env.production 또는 .env.development
.env

값의 존재와 올바름을 배포에서 검증해

빌드가 통과해도 잘못된 endpoint나 빈 공개 값은 실행 중에만 드러날 수 있어. 비밀을 출력하지 않는 health check와 실제 핵심 요청으로 환경별 계약을 확인해.

같은 Docker 이미지를 두 환경에 배포하고 공개 변수와 서버 변수가 실제로 언제 달라지는지 테스트로 증명해. 설정 이름·필수 여부·공개 범위·회전 주기를 schema로 관리하고 시작 시 잘못된 서버 값은 빠르게 실패시켜. 클라이언트 값은 빌드 manifest로 배포와 연결해. 환경 값을 바꾼 뒤에는 새 배포와 기존 인스턴스를 동시에 요청해 혼합 상태가 생기는지 봐. 롤링 배포 동안 두 값이 공존할 수 있다면 데이터 형식과 기능 플래그도 그 구간을 견뎌야 해. 실행 시점 설정이 더 유연하다고 모든 값을 API로 내려 주면 첫 렌더와 캐시가 복잡해지고 공개 범위도 넓어져. 반대로 빌드 시점 값은 변경마다 새 이미지를 요구해. 값이 배포와 함께 버전되어야 하는지 운영 중 바뀌어야 하는지로 선택해. 하나의 이미지를 staging과 production에 배포해 NEXT_PUBLIC_ 값이 같고 서버 변수는 실행 환경을 따르는지 페이지와 서버 로그로 확인해. 환경별 재빌드 또는 runtime 설정 endpoint를 적용한 뒤 cache가 다른 환경 값을 섞지 않는지도 시험해.

Code

환경 변수를 요청 시점에 읽기·tsx

import { connection } from 'next/server';

export default async function Page() {
  await connection(); // 요청별 렌더링을 명시적으로 선택
  const apiUrl = process.env.API_URL; // 요청마다 읽기
  return <div>API: {apiUrl}</div>;
}

Vercel CLI에서 환경 범위 지정하기·bash

vercel env add DATABASE_URL production
vercel env add DATABASE_URL preview
vercel env add DATABASE_URL development

공개 변수와 서버 변수는 굳는 시간이 달라

Docker 이미지 하나로 공개 설정을 바꿀 수 없어

환경 파일 우선순위를 알아 둬

값의 존재와 올바름을 배포에서 검증해

Code

External links

Exercise

Progress

댓글 0