배포 환경에서만 깨지는 문제, 환경변수부터 본다

환경변수는 코드와 분리된 설정이다

API 키, 외부 서비스 주소, 사이트 도메인처럼 환경마다 달라질 수 있는 값을 코드에 직접 적어두면, 로컬과 배포 환경이 같은 값을 공유하게 되어 둘 중 하나에서 문제가 생깁니다. 환경변수로 분리해두면 코드는 그대로 두고 환경별로 다른 값을 주입할 수 있습니다.

로컬과 배포 환경의 차이가 드러나는 지점

로컬 개발 서버는 보통 개발자가 직접 만든 .env 파일을 읽지만, 배포 플랫폼은 별도의 환경변수 설정 화면에 값을 등록해야 합니다. 이 둘은 서로 자동으로 동기화되지 않으므로, 로컬에 새 환경변수를 추가했다면 배포 환경에도 같은 이름과 값을 등록했는지 확인해야 합니다.

환경변수가 누락되면 빌드 자체는 성공하더라도, 해당 값을 사용하는 페이지나 기능에서만 오류가 발생합니다. “빌드는 성공했는데 특정 페이지만 깨진다”는 증상은 환경변수 누락을 의심해볼 만한 신호입니다.

공개 변수와 비공개 변수를 구분한다

Next.js에서는 이름이 특정 접두사로 시작하는 환경변수만 브라우저로 전달되고, 그렇지 않은 변수는 서버에서만 사용됩니다. 이 구분을 모르고 비공개로 남겨야 할 값에 공개 접두사를 붙이면 클라이언트에 그대로 노출될 수 있고, 반대로 브라우저에서 필요한 값에 접두사를 빠뜨리면 화면에서 undefined로 보이게 됩니다.

배포 전 점검 목록에 “이번 배포에서 새로 추가하거나 바꾼 환경변수 목록”을 짧게 적어두면, 배포 후 문제가 생겼을 때 가장 먼저 확인할 후보를 바로 좁힐 수 있습니다.