배포하면 환경변수 에러가 나는 이유 몇 가지

배포할 때마다 환경변수 문제가 나오는 건 로컬과 서버 사이의 차이가 .env 파일 관리 방식에서 나오기 때문이다. 빌드 타임과 런타임을 구분하지 않으면 같은 실수를 반복하게 된다.

NEXT_PUBLIC_ 접두사 혼동

Next.js에서 클라이언트 사이드에서 쓸 환경변수는 반드시 NEXT_PUBLIC_ 접두사가 붙어야 빌드 결과물에 포함된다. 서버에서만 쓰는 변수에 이 접두사를 붙이면 클라이언트에 값이 노출되고, 반대로 클라이언트에서 필요한 변수에 접두사가 없으면 undefined가 된다.

npm run build 2>&1 | grep -i "env\|undefined"

빌드 로그에 경고가 나오면 어떤 변수가 누락됐는지 거기서 확인할 수 있다.

.env 파일이 배포에서 빠진 경우

.gitignore에 .env가 들어 있는 건 맞지만, 서버에 .env를 직접 두고 관리하는 방식이라면 배포 스크립트가 그 파일을 덮어쓰거나 지우지 않도록 주의해야 한다. Docker 빌드라면 .dockerignore가 .env를 제외하고 있을 수 있다.

빌드타임과 런타임 혼동

Next.js, Vite 같은 프레임워크는 빌드 단계에서 환경변수를 번들에 주입한다. 빌드 후에 서버에서 환경변수를 바꿔도 이미 번들에 박힌 값은 바뀌지 않는다. 값을 바꿨으면 반드시 다시 빌드해야 반영된다.

빠른 확인 순서

1. 빌드 에러 메시지에서 어떤 변수가 없다고 나오는지 확인한다.
2. .env.production과 코드에서 process.env.XXX로 참조하는 키 목록을 나란히 놓고 비교한다.
3. 클라이언트에서 쓰는 변수라면 NEXT_PUBLIC_ 접두사 여부를 확인한다.
4. 빌드가 어느 시점에 실행됐는지, 그 시점에 환경변수가 설정돼 있었는지 확인한다.

처음부터 필수 환경변수를 앱 시작 시점에 검증하는 코드를 넣어두면 에러 메시지가 훨씬 명확해진다.