검색 결과로 찾은 코드, 로컬에선 되는데 배포하면 안 될 때

StackOverflow나 GitHub 이슈에서 찾은 코드가 로컬에선 완벽하게 작동하는데 배포하면 실패하는 경우가 있다. 이럴 때는 세 곳의 차이를 찾아야 한다.

첫 번째 단서: 빌드 결과

# 로컬에서
npm run build

# 배포 환경의 빌드 로그 확인
# docker build ... (또는 CI/CD 파이프라인)

로컬 빌드는 성공했지만 배포 환경에서 경고나 에러가 있을 수 있다. 환경 변수 치환 차이, Node 버전 차이 등이 원인이다.

두 번째 단서: 환경 변수

# 로컬에서
echo $DATABASE_URL
echo $NODE_ENV

# 배포 환경에서
# .env, .env.production, docker 환경 변수 등 여러 곳에서 나올 수 있음

예를 들어 로컬에선 NODE_ENV=development이고 배포에선 production일 수 있다. 이게 코드 동작을 크게 바꾼다.

세 번째 단서: 의존성 버전

# 로컬에서 설치된 버전
npm list react react-dom

# 배포에서 설치되는 버전
# package-lock.json이 lock하는 버전
cat package-lock.json | grep '"version"' | head -20

로컬에선 최신 버전이지만 배포 이미지는 몇 달 전 버전일 수 있다.

확인 순서

1. 빌드 로그: 로컬과 배포 모두 성공? 경고는?
2. 환경 변수: .env 파일의 내용이 다른가?
3. 응답 코드: API 호출이 성공? 실패? 타임아웃?
4. 콘솔 로그: 브라우저 콘솔과 서버 로그에 에러가?

작은 변경부터

코드를 여러 개 적용했으면 하나씩만 테스트한다.

# 1. 코드 1개 적용
git apply patch1.diff
npm run build
# 배포해서 테스트

# 2. 코드 2개 적용
git apply patch2.diff
npm run build
# 배포해서 테스트

뭐가 터졌는지 빠르게 특정할 수 있다.

결국 검색으로 찾은 솔루션도, 자기 프로젝트의 환경에 맞게 검증해야 진짜 해결책이 된다.