(Node.js)(Next.js) SSR 에서 localhost 연결 안되는 이슈 원인 & 해결방안

 

웹 서비스를 로컬 개발하다가 팀원의 컴퓨터에서 재미난 이슈를 발견하여 포스팅해본다.

 

 

 

문제상황

클라이언트 사이드에선 말짱히 잘 조회되는 localhost url이
서버 사이드에선 조회가 안된다.

api url : http://localhost:3000/api/v1 ...

fetch, axios 그 어떤걸 써봐도 동일하다

 

 

해결방법 먼저

첫번째 해결 방법.

 

node.js 버전이 17~23이고, 조금 낮은 버전대라면,

node.js 최신 버전으로 업데이트를 해보자.

 

이 이슈가 정확히 몇버전에서 완전히 해결되었는지까진 전부 파악하지 못하였지만,
우선 내가 확인한 Node.js의 최신 버전들에선 대부분 localhost IPv6 요청이 실패했을때 자동으로 IPv4 요청으로 재시도시켜주는 로직이 추가되어있었다.

 

확인해본 버전

17.2 이슈 발생, 17.9 로 업그레이드 후 이슈 해결

18.11 이슈 발생, 18.20 이슈 해결

23.12 이슈 발생, 23.16 이슈 해결

 

 

 

두번째 해결 방법.

 

만약 모든 디바이스에서 Node.js 버전을 일일히 업그레이드하기 힘들 경우 쓸수 있는 방법이다.

 

next.js 기준,

package.json 파일 내 run 스크립트에 아래 명령어를 추가하자.

 

--dns-result-order=ipv4first

 

...
  "scripts": {
    "dev": "cross-env NODE_OPTIONS=\"--dns-result-order=ipv4first\" next dev --port 8000",
    "start": "next start --port 8000",
  }
...
  "dependencies": {
    "cross-env": "^7.0.3",
...

 

 

그럼 기적처럼 SSR에서 localhost 주소를 조회할 수 있게 된다.

next.js 뿐만 아니라 Node.js 라면 사용 가능한 명령어다.
단, Node.js 17 버전 이후부터 사용 가능하다.

 

 

 

원인을 파악해봅시다.

 

이 이슈엔 재미난 특이점들이 있었다.

분명 똑같은 url 인데 CSR에선 되고 SSR에선 안된다?
내 맥에선 되는데 동료 팀원의 윈도우에선 안된다?

내가 찾아본 원인은 다음과 같다.

 

 

os 레벨에서 localhost가 기본적으로 IPv6(::1)와 IPv4(127.0.0.1) 두개다 매핑이 되어있는데

localhost 요청을 실행할때 Node.js 17~ 초반대 버전의 런타임이 우선 ::1 로 먼저 시도했다가

해당 서버가 IPv6 바인딩이 없으면 연결이 거부되어 실패하고,

그 뒤 IPv4 시도로 넘어가지 않아 요청이 최종적으로 실패하는 현상이 발생하는걸로 추측된다.

 

관련 이슈.

"localhost" favours IPv6 in node v17, used to favour IPv4

Node.js 16 -> 17 changed resolution of "localhost"?

 

내 맥에선 왜 되었는지 파악해보니, 내 맥의 Node.js 버전은 22.16이였고, 22.12로 다운그레이드시 동일 이슈가 발생함을 확인하였다.

윈도우 또한 Node.js를 최신버전으로 업그레이드하니 이슈가 해결됨을 확인했다.

 

 

아마도 추측으론, 이 Node.js 18.16 버전의 이 커밋처럼,

https://github.com/nodejs/node/commit/0edaf016cc

최근의 Node.js 버전들에선 엔진 내부에서 IPv6 요청이 실패시 IPv4로 재시도 시켜주는 로직이 새로이 추가되었기에,

 

node.js의 버전 업그레이드를 통해 localhost에 요청을 못보내는 이슈를 해결할 수 있었다.

 

추가로, 위에서 해결방법으로 기술한 것처럼
Node.js가 localhost 로 연결 시도 시 IPv4 를 우선적으로 조회하도록 요청하는 커멘드를 사용할 수도 있다.