빌드 환경변수가 적용되지 않을 때 확인할 것

Next.js나 다른 웹 프레임워크에서 환경변수를 설정했는데 배포하면 먹지 않는 경우가 있다. 이는 보통 빌드 타임 변수와 런타임 변수를 헷갈리기 때문이다.

빌드 타임 변수 vs 런타임 변수

빌드 타임 변수: 빌드할 때 값이 고정된다. 나중에 바꿀 수 없다. (예: API_URL_BUILD) 런타임 변수: 서버가 실행될 때 읽는다. 언제든 바꿀 수 있다. (예: DATABASE_URL)

Next.js에서 NEXT_PUBLIC_로 시작하는 변수는 빌드에 포함되어 클라이언트에도 노출된다. 그래서 민감한 정보를 여기 넣으면 안 된다.

npm run build

빌드 로그를 보면 어떤 환경변수가 사용되었는지 확인할 수 있다.

.env 파일과 .env.local

.env 파일은 버전 관리에 포함되고, .env.local은 로컬 개발용으로 .gitignore에 들어간다.

배포 환경에서는 보통 .env.local이 없으므로, 배포 서버의 환경변수나 CI/CD 시스템에서 직접 주입해야 한다.

Dokploy나 다른 배포 도구를 쓴다면, 그곳의 환경변수 설정 ui에서 값을 입력하거나, 배포 스크립트에서 export로 주입할 수 있다.

각 단계에서 변수 확인

환경변수가 제대로 적용되는지 다음 단계마다 확인한다:

1. 로컬 개발: npm run dev 에서 console.log로 변수 출력
2. 로컬 빌드: npm run build 후 npm run start에서 변수 출력
3. 배포 환경: 실제 서버에서 변수 확인

# 배포된 앱에서
curl https://example.com/api/health  # 응답에 환경변수가 포함되어 있나?

빌드 캐싱으로 인한 변수 미적용

Docker를 쓰는 경우, 이전 빌드 레이어가 캐싱되어 있으면 환경변수를 다시 읽지 않을 수 있다.

Docker 빌드할 때 --no-cache 플래그를 쓰거나, Dockerfile에서 환경변수 변경을 감지하도록 설정해야 한다.

우선순위 확인

환경변수는 여러 곳에서 정의될 수 있다:

1. .env
2. .env.local
3. .env.production
4. 시스템 환경변수 (export)
5. CI/CD 플랫폼의 시크릿/환경변수

어느 곳이 가장 높은 우선순위를 가지는지 프레임워크 문서에서 확인하고, 각 단계에서 어느 값이 사용되는지 확인하자.

빌드 컨텍스트 환경변수 주입

CI/CD에서 빌드할 때 환경변수를 주입하는 방식도 중요하다.

# GitHub Actions 예
env:
  API_URL: ${{ secrets.API_URL }}
npm run build

이렇게 하면 빌드 시점에 변수가 적용된다.

배포 후 변수 변경이 필요하면

배포 후 환경변수를 바꿔야 한다면, 빌드에 포함되지 않는 런타임 환경변수만 가능하다는 걸 기억해야 한다.

빌드에 포함된 변수를 바꾸려면 다시 빌드해서 배포해야 한다.