환경변수가 제대로 안 들어갔을 때 확인 방법

Next.js에서 환경변수가 제대로 작동하지 않아서 당한 일을 정리했다.

빌드 타임과 런타임 구분

Next.js는 NEXT_PUBLIC_ 접두사가 있는 변수는 빌드 타임에 번들로 포함시키고, 그렇지 않은 변수는 런타임에 찾는다. 이 둘을 헷갈리면 안 된다.

로컬 .env.local에는 있는데 배포 후 안 되는 경우는 보통 런타임 변수 설정을 깜빡했기 때문이다.

HTML head에서 확인

NEXT_PUBLIC_ 변수가 제대로 들어갔는지 확인하려면, 브라우저에서 페이지 소스를 본다. 번들 안에 값이 하드코딩되어 있으면 제대로 들어간 것이다.

curl -s https://example.com | grep "<script" | head -1

빌드 로그 확인

배포할 때 빌드 로그를 찍어두면, 나중에 환경변수 값이 제대로 읽혔는지 확인할 수 있다.

npm run build
# 로그에 "environment loaded" 같은 메시지가 있는지 확인

배포 환경마다 환경변수를 다르게 설정해야 하는 경우가 많으니, 각 환경마다 뭐가 다른지 문서에 남겨두면 나중에 새로운 환경을 추가할 때 헷갈리지 않는다.