환경변수 문제 빠르게 디버깅하기

환경변수 문제는 로컬에서는 잘 돌다가 배포 환경에서만 터지는 경우가 많다. 이럴 땐 처음부터 정답을 맞히려고 하면 오히려 시간이 오래 걸린다. 대신 증거를 차근차근 모으는 게 빠르다.

먼저 확인할 것

환경변수 문제일 가능성이 높으면, 일단 다음을 순서대로 기록한다:

• 정상일 때의 환경 상태는 어떤가?
• 지금 에러의 증상은 무엇인가?
• 로그나 응답에서 뭐가 바뀌었나?

설정부터 확인하자

바로 코드를 고치기 전에 설정 파일을 먼저 본다. 불필요한 변경을 줄일 수 있다.

# .env 파일 확인
cat .env
# 또는 배포된 환경에서
env | grep -E 'DATABASE|API|KEY'

한 번에 한 가지만 바꿔라

환경변수를 여러 개 한 번에 수정하면 뭐 때문에 원인이 바뀐 건지 알기 힘들다. 한 개씩 바꾼 다음 확인하는 습관이 중요하다.

1. 현재 증상을 정확히 기록한다 (로그, 에러메시지, 응답 상태)
2. 의심되는 환경변수 하나만 바꾼다
3. 같은 조건에서 다시 시도해서 뭐가 바뀌었는지 확인한다
4. 바뀐 게 없으면 그 설정은 원인이 아니다

실제 운영 환경과 비교하기

로컬에서 테스트할 땐 .env 파일을 수정하고, 배포 후엔 서버의 환경변수를 확인하는 게 기본이다. 배포 도구(Dokploy, Docker, 등)에서 환경변수가 제대로 전달되는지 꼭 확인하자.

관련 기록을 남겨두면 다음에 같은 문제가 나올 때 훨씬 빨리 찾을 수 있다.