웹 개발할 때 네트워크 요청이 막힐 때 순서대로 확인하는 법

웹 개발 중에 API 요청이 안 되면 답답하다. 네트워크가 문제인지, 코드가 문제인지, 서버가 문제인지 먼저 구분해야 한다.

1단계: 브라우저 개발자 도구에서 확인하기

가장 먼저 개발자 도구의 Network 탭을 열고, 요청이 정말 나가는지 확인하자. 혹은 나가지 않는지 보자. 요청이 나갔다면 상태 코드는 뭔지, 응답 헤더는 뭔지 확인해야 한다. CORS 에러라면 Access-Control-Allow-Origin 헤더가 없을 것이고, 인증 에러라면 401 상태 코드가 올 것이다.

2단계: 요청 URL과 헤더가 정확한지 확인하기

개발 환경에서 요청하는 URL과 실제 API 서버의 주소가 같은지 확인하자. 혹은 다른 환경 변수를 사용 중인지 확인해보자. 요청 헤더에 인증 토큰이 제대로 붙어있는지, Content-Type은 맞는지 살펴보자. 특히 CORS 요청이라면 preflight 요청이 나가고, 그 응답이 200 OK인지 확인해야 한다.

npm run build

3단계: 로컬 개발 서버가 제대로 뜨는지 확인하기

혹시 웹팩이나 Vite 같은 개발 서버가 에러로 실패했거나 재시작된 건 아닌지 확인하자. 터미널을 보고 에러 메시지가 있는지 살펴보자. 포트가 변경되지는 않았는지, 핫 리로드는 되는지 확인해보면 좋다.

4단계: API 서버 상태 확인하기

요청이 나갔는데 응답이 오지 않는다면, 실제 API 서버가 뜨는지 확인하자. 서버 로그를 확인하고, 포트가 열려있는지 netstat이나 ss 명령으로 확인해보자. 혹은 curl이나 Postman 같은 도구로 직접 API를 호출해서 서버가 응답하는지 테스트해보자.

5단계: 네트워크 문제와 설정 문제 구분하기

같은 라우터나 Wi-Fi에 있는데 다른 기기에서는 정상적으로 접근되는지 확인해보자. 혹은 같은 웹사이트에 있는 다른 API는 정상인지 확인하면 된다. 만약 특정 도메인만 막힌다면 방화벽이나 네트워크 설정 문제일 가능성이 높다.

6단계: 환경별로 엔드포인트 다시 확인하기

로컬 개발, CI 환경, 스테이징, 운영 환경에서 각각 다른 API 서버를 쓰고 있을 수 있다. 빌드 타입에 따라 올바른 환경 변수가 로드되는지 확인하자. 번들링할 때 실수로 하드코딩된 주소가 섞여있는 건 아닌지도 다시 확인해보자.

정보를 기록하고 다음 번에 참고하기

한 번 해결한 문제를 다시 만나면 이전 경험을 참고할 수 있도록 로그를 남겨두자. 요청과 응답, 에러 메시지, 해결 방법을 정리해두면 다음 번에는 훨씬 빠르게 문제를 해결할 수 있다.