서버에서만 실패하는 빌드 문제 디버깅하기

로컬 개발 환경과 운영 서버는 전혀 다른 곳이다. 설치된 패키지, 환경 변수, 리소스(CPU, 메모리, 디스크), 네트워크 상황이 모두 다르다. 로컬에서는 잘 작동하는 빌드가 운영 서버에서만 실패하는 일이 자주 생긴다. 이런 문제는 화면만 보고는 해결할 수 없다. 로그와 프로세스 상태를 동시에 봐야 한다.

상황 요약하기

먼저 문제가 언제 시작됐는지, 마지막 성공한 배포는 언제인지, 그 사이에 뭐가 바뀌었는지 정리한다. 코드? 환경 변수? 인프라?

서버 상태 확인

가장 기본적인 것부터 확인한다. 디스크 공간, 메모리, CPU 사용률.

df -h          # 디스크 사용 현황
free -h        # 메모리 사용 현황
uss -lntp      # 열려있는 포트 확인

빌드 로그 읽기

CI/CD 파이프라인의 로그를 자세히 본다. 어디서 실패했는지, 어떤 에러인지 정확히 찾는다.

sudo journalctl -n 80        # 최근 시스템 로그 확인
docker logs service-name     # 컨테이너 로그

환경 변수와 설정 검증

로컬에서는 .env 파일이 있고, 운영 서버에서는 환경 변수가 정의되어 있다. 실제로 필요한 모든 변수가 정의됐는지 확인한다.

• 확인할 것: 환경 변수, 포트 설정, 리소스 제한
• 비교 기준: 이전 성공한 배포의 설정
• 기록할 것: 오류 메시지, 사용 가능한 리소스, 설정 값

작은 실험부터 시작

전체 빌드를 다시 하지 말고 문제 부분을 먼저 고립시킨다. 패키지 설치? 번들링? 런타임?

npm ci                    # 의존성 정확히 설치
npm run build             # 빌드만 실행

권한 확인

로컬에서는 관리자 권한으로, 서버에서는 제한된 권한으로 실행할 수 있다. 파일 생성, 포트 바인딩, 디렉토리 쓰기 등이 가능한지 확인한다.

완료 기준

1. 실패 지점을 로그로 명확히 설명할 수 있는가
2. 로컬과 운영 환경의 차이를 찾을 수 있는가
3. 해결 방법을 실행 명령어로 설명할 수 있는가

운영 서버의 문제는 다양한 변수가 얽혀있기 때문에 한 가지씩 제외하면서 진행하는 것이 가장 효율적이다.