웹 빌드 결과가 로컬과 배포 서버에서 다를 때

웹 애플리케이션 개발에서 가장 지루한 순간은 로컬에서는 완벽한데 배포 환경에서만 문제가 생기는 경우다. 이런 상황을 빠르게 진단하려면 환경 차이를 명확히 이해해야 한다.

빌드 프로세스부터 체크하기

먼저 빌드 과정에서 에러가 없는지 확인한다. 로컬에서 실행할 때와 배포 서버에서 실행할 때 다른 결과가 나올 수 있다.

npm run build

빌드 로그를 끝까지 꼼꼼히 읽어야 한다. 경고(warning)는 무시하기 쉽지만, 때로는 이 경고가 실제 문제로 이어진다. 특히 번들 크기가 너무 크거나 트리쉐이킹이 제대로 되지 않은 경우를 놓치기 쉽다.

환경 변수 확인하기

ローカル開発環境と本番環境は환경 변수가 다르다. 로컬에서는 .env.local을 쓰지만 배포 서버에서는 시스템 환경 변수나 다른 파일을 사용할 수 있다.

• .env 파일이 제대로 로드되는가
• 필수 환경 변수가 모두 설정됐는가
• API 엔드포인트 URL이 서버별로 제대로 다른가

이런 것들을 확인해야 한다.

의존성 버전 일치시키기

로컬과 서버에서 설치된 npm 패키지 버전이 다르면 동작도 다를 수 있다. package-lock.json이나 yarn.lock을 커밋해서 버전을 고정하는 게 중요하다.

배포 후 실제 화면 확인하기

빌드가 성공했다고 해서 배포가 성공한 건 아니다. 실제 서버에 배포된 후 :

1. 브라우저 개발자 도구의 콘솔을 열어 에러가 있는지 확인한다.
2. 네트워크 탭에서 실패한 요청이 있는지 본다.
3. 주요 기능들을 직접 클릭해서 작동하는지 확인한다.

캐시 문제 고려하기

배포 후에도 브라우저 캐시 때문에 이전 버전이 보일 수 있다. 브라우저를 완전히 새로고침하거나 시크릿 창에서 확인해보면 좋다.

로컬과 배포 환경의 작은 차이들이 모여서 예상치 못한 문제를 만든다. 체계적으로 각 부분을 확인하면 원인을 빠르게 찾을 수 있다.