API 연동이 로컬에서는 되는데 배포하면 실패하는 이유

로컬과 배포 환경의 차이를 먼저 의심하자

API 연동이 로컬에서는 완벽한데 배포 후 실패하는 경우는 다음 요인들이 대부분이다:

• 환경 변수 설정 오류 (API 주소, 토큰)
• 인증 상태 차이
• 요청 헤더의 Content-Type 불일치
• CORS 설정 미반영

나는 이런 문제를 마주칠 때마다 다음 순서로 체크한다.

실제 요청 확인하기

# 배포 환경에서 직접 curl 테스트
curl -i -X GET 'https://example.com/api/endpoint' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

응답 헤더와 body를 먼저 본다. 다음을 체크한다:

• HTTP 상태 코드 (200, 401, 403, 500?)
• Content-Type이 application/json인가?
• 에러 메시지가 명확한가?

로컬에서 같은 요청을 날렸을 때와 비교하면 차이를 발견할 수 있다.

서버 로그 확인하기

배포 환경의 API 서버 로그를 봐야 한다. 요청이 도달했는지, 도달했다면 어디서 실패했는지 파악할 수 있다.

내 경험상 가장 흔한 실수:

• 환경 변수 파일을 배포 환경에 복사하지 않음
• 배포 후 환경 변수를 다시 설정하지 않음
• 로컬 개발에서만 사용하는 목 데이터를 배포 환경에서도 참조

한 가지씩만 바꾸기

여러 설정을 동시에 변경하면 문제 해결이 어렵다. 환경 변수를 하나 수정하고 배포한 후 다시 테스트하는 식으로 진행한다. 이렇게 하면 어느 설정이 문제인지 명확해진다.

작은 성공을 기록해두는 게 좋다. 다음에 비슷한 문제가 발생했을 때 훨씬 빨리 해결할 수 있다.