웹 개발 배포 후 문제를 빠르게 추적하는 방법

배포 후에 로컬에서는 안 보이던 문제들이 자주 나타난다. 이런 상황에서 패닉하지 않고 빠르게 원인을 찾으려면 확인해야 할 항목들을 미리 정해두는 게 좋다.

먼저 빌드 결과부터 본다

npm run build

빌드 과정에서 경고나 에러가 있으면 배포 후에도 문제가 될 가능성이 높다.

빌드 결과 파일 크기를 확인한다:

du -sh .next/  # 전체 빌드 크기
du -sh .next/static/  # 정적 파일 크기

예상보다 크면 불필요한 번들이 포함됐을 수 있다.

배포 환경에서 애플리케이션 로그

배포한 애플리케이션의 로그를 본다:

# SSH로 서버 접속 후
less /var/log/application.log  # 또는 해당 로그 경로

# 또는 Docker 로그
docker logs service-name

시작 시간부터의 모든 로그를 본다. 경고도 무시하지 말자.

실행 환경 변수 확인

배포 환경에서 환경 변수가 제대로 설정됐는지 확인한다:

env | grep -i NODE  # Node.js 관련 변수
env | grep -i DATABASE  # DB 관련 변수

로컬에서는 .env 파일에서 읽지만, 배포 후에는 시스템 환경 변수나 설정 파일에서 읽을 수도 있다.

애플리케이션이 올바른 포트를 듣고 있는지

sudo ss -lntp | grep node

예상한 포트에서 리스닝하는지 확인한다.

네트워크 연결 확인

API 엔드포인트나 외부 서비스에 연결되는지 확인한다:

curl -I https://api.example.com/health

또는 서버 내부에서:

curl http://localhost:3000/

문제가 있는 특정 경로 테스트

가장 먼저 문제가 보인 경로를 테스트한다:

curl -v https://example.com/problematic-path

응답 코드, 헤더, 본문을 모두 본다.

프로덕션 모드에서 로컬 테스트

배포 전에 로컬에서 프로덕션 모드로 테스트한다:

npm run build
npm run start  # 프로덕션 서버 시작

curl http://localhost:3000/  # 다른 터미널에서

이렇게 하면 배포 전에 많은 문제를 발견할 수 있다.

캐시 무효화

브라우저 캐시 때문에 이전 버전이 보일 수도 있다:

# Hard refresh (Ctrl+Shift+R 또는 Cmd+Shift+R)
# 또는 DevTools에서 캐시 비우기

확인 리스트

1. 로컬 빌드 성공 확인
2. 배포 서버의 로그 확인
3. 환경 변수 확인
4. 포트 리스닝 확인
5. 네트워크 연결 확인
6. 특정 경로 테스트
7. 프로덕션 모드 로컬 테스트
8. 캐시 무효화

이 정도만 체계적으로 확인하면 대부분의 배포 후 문제를 해결할 수 있다.