Docker Dev Container 환경에서 Vite + React 프로젝트를 실행했는데, yarn dev를 했을 때 VS Code Ports에는 5173이 보이지만 브라우저로 접속이 안되는 문제가 발생했습니다.

환경

• React + Vite + Yarn
• Docker Dev Container
• VS Code + Dev Containers extension
• devcontainer.json은 아래와 같이 설정되어 있었습니다.

  {
    "name": "react-vite-dev",
    "image": "node:20",
    "forwardPorts": [5173],
    "customizations": {
      "vscode": {
        "extensions": [
          "dbaeumer.vscode-eslint", // ESLint
          "esbenp.prettier-vscode", // Prettier
        ],
      }
    }
  }
  

  포트 포워딩을 위해 forwardPorts에 5173을 지정했습니다.
  

컨테이너 내부

Docker Desktop에서 컨테이너 터미널에 접속해 curl http://localhost:5173을 실행했습니다.

HTML이 정상적으로 출력되었고, Vite 서버는 컨테이너 내부에서 5173 포트를 정상적으로 리슨하고 있음을 확인할 수 있었습니다.

VS Code 포트 포워딩 로그 확인

하지만 브라우저에서는 접속되지 않은 것으로 보아 문제는 컨테이너 → 로컬로 포트가 제대로 포워딩되지 않은 것 같았습니다. VSCode 로그를 확인하니 다음과 같은 에러가 출력되었습니다.

• VS Code가 포트포워딩을 잡으려고 컨테이너 내부의 127.0.0.1:5173에 접속했는데 그 순간 ECONNREFUSED에러가 났습니다. 즉, 그 시점에 5173에서 리슨 중인 프로세스가 없었다는 의미의 에러입니다.

원인: Vite의 기본 바인딩 방식

yarn dev로 실행했을 때의 Vite 로그를 보면 다음과 같은 메세지가 나옵니다.

이는 Vite가 기본적으로 127.0.0.1 (localhost)에만 바인딩되어 실행되고 있으며, 외부 네트워크 접근은 허용하지 않고 있다는 의미입니다.

해결: 모든 인터페이스에 바인딩

그래서 vite를 yarn dev --host 0.0.0.0로 실행했습니다.

Network 주소가 표시되고 브라우저에서도 정상적으로 접속되었습니다.

127.0.0.1은 루프백(loopback) 주소로, 해당 네트워크 네임스페이스(여기서는 컨테이너) 자기 자신만 접근 가능한 주소입니다.

즉,

• 컨테이너의 127.0.0.1 ≠ 호스트 PC의 127.0.0.1
• 포트 포워딩은 컨테이너의 네트워크 인터페이스로 들어오는데
• 서버가 127.0.0.1에만 바인딩되어 있으면 외부 요청을 받지 않습니다.

그래서 컨테이너의 127.0.0.1이기 때문에 내 PC에서는 접근할 수 없습니다.

[브라우저]
   ↓
[호스트 localhost:5173]
   ↓ (포트 포워딩)
[컨테이너 네트워크 인터페이스]
   ↓
[Vite 서버]

그래서 포트는 열려 있지만 서버가 요청을 거부(ECONNREFUSED) 하게 됩니다.