배포 전에 확인해야 할 환경변수 체크리스트

배포 전 마지막 순간에 속도가 느려지거나 예상 밖의 동작이 나타난다. 대부분 환경변수 설정이 맞지 않거나, 로컬과 배포 환경이 다를 때다.

왜 환경변수 때문에 헷갈리나

개발할 때는 하드코딩하거나 .env.local 파일을 쓴다. 그런데 배포할 때는 CI/CD 도구나 클라우드 플랫폼에서 환경변수를 설정한다. 이 두 설정이 불일치하면 문제가 생긴다.

Next.js의 경우 빌드 시점에 환경변수가 고정되는데, 런타임에 다른 값을 넣으면 효과가 없다.

빌드할 때 어떤 환경변수가 사용되는가

npm run build

빌드 로그를 보면 환경변수들이 나타날 수 있다. 혹은 빌드 후 생성된 .next 폴더의 파일들을 보면, 환경변수가 정말 대체되었는지 확인할 수 있다.

재현 조건을 정확히 기록하기

문제를 재현할 수 있는 정확한 조건을 남겨둬야 한다. 어떤 URL에서 문제가 나는가? 어떤 브라우저에서 나는가? 로그인 후에만 나타나는가?

설정 파일 체크 포인트

필수 환경변수 목록을 만들자:

• API 엔드포인트
• CDN URL
• 데이터베이스 연결 문자열
• 디버그 모드 (온/오프)
• 사이트 도메인

이들 각각이 배포 환경에서 올바른 값으로 설정되어 있는가?

실행 예시: 로그로 확인하기

애플리케이션 시작 시 현재 설정을 로그로 출력하도록 하면 좋다. 그럼 배포 후 정말 어떤 값이 사용되는지 명확해진다.

사용자 영향 실제로 보기

로컬에서 테스트하는 것과 실제 배포 환경은 다르다. 공개 URL을 직접 열어보고, 응답 시간, 로딩 상태, 기능 작동을 모두 확인한다.

한 번에 여러 환경변수를 바꾸지 말 것. 하나씩 고쳐보고 배포한 후 결과를 확인하면, 어디서 문제가 풀렸는지 명확해진다.

마지막으로 이번 배포에서 어떤 설정이 달라졌는지, 왜 그렇게 했는지를 기록해두면, 다음에 비슷한 상황이 나올 때 훨씬 빠르게 대응할 수 있다.