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

시나리오 — 로컬은 되는데 배포만 안 된다

빌드는 초록불인데, 배포된 사이트에서 특정 버튼을 누르면 아무 반응이 없습니다. 로컬에서는 같은 버튼이 멀쩡히 동작합니다. 콘솔을 열어보면 클라이언트 컴포넌트 안에서 참조하던 값이 undefined로 찍혀 있습니다.

'use client';

// .env에는 있지만 배포 환경변수 설정 화면에는
// 접두사 없이 SITE_API_BASE로만 등록돼 있었음
const apiBase = process.env.NEXT_PUBLIC_SITE_API_BASE;

fetch(`${apiBase}/submit`); // apiBase가 undefined → "undefined/submit" 요청

원인을 좁히는 과정

빌드가 성공했다는 것은 코드 문법에 문제가 없다는 뜻이지, 런타임에 필요한 값이 다 채워졌다는 뜻은 아닙니다. "빌드는 됐는데 특정 기능만 깨진다"는 증상이 나오면, 그 기능이 참조하는 환경변수부터 의심하는 편이 빠릅니다.

이 사례의 원인은 두 가지가 겹친 것이었습니다. 첫째, 로컬 .env에는 NEXT_PUBLIC_SITE_API_BASE로 등록했지만 배포 플랫폼의 환경변수 설정 화면에는 SITE_API_BASE로 접두사 없이 등록돼 있었습니다. 둘째, Next.js는 NEXT_PUBLIC_ 접두사가 붙은 변수만 클라이언트 번들에 포함시키므로, 접두사가 빠진 변수는 빌드 시점에 조용히 undefined로 치환됩니다. 에러가 나지 않고 그냥 undefined가 되기 때문에 발견이 늦어집니다.

고치고 나서 남긴 것

조치는 배포 환경변수 이름을 로컬 .env와 정확히 일치시키는 것으로 끝났지만, 재발을 막으려면 "이번 배포에서 새로 추가하거나 바꾼 환경변수 목록"을 배포 전 체크리스트에 한 줄로 남기는 습관이 더 중요했습니다. 이름이 다른 것 하나로 몇 시간이 날아갈 수 있다는 걸 알고 나면, 이 한 줄을 아끼기 어려워집니다.