開發者

容器無法連到 Mac 上的 localhost

每個容器都有自己的網路堆疊。在容器內，localhost 是容器本身，而不是 Mac。

適用於：目前 macOS 版本上的 Docker Desktop 和 OrbStack。檢查日期：2026年10月29日

症狀

  • 容器內的 App 連線到 localhost:5432 或類似的連接埠時出現「connection refused」。
  • 同一個 URL 在 Mac 上的 Safari 或「終端機」中可以正常使用。
  • 開發容器連不到 Mac 上的模型伺服器或 API。

可能原因

  • localhost 指向容器。容器會在自己的網路堆疊中尋找服務，但那裡沒有任何程式在監聽。
  • 主機位址會改變。Docker 說明文件指出主機的 IP 位址會變動，因此另外提供一個代表主機的特殊名稱。
  • Mac 上的防火牆。macOS 防火牆或其他防火牆 App 可能會阻擋連到該服務的傳入連線。

如何檢查

  1. 確認服務在 Mac 上可以正常運作。將 8000 換成你的連接埠。

    curl http://localhost:8000

  2. 查看 Mac 上的服務監聽哪個位址。

    lsof -nP -iTCP:8000 -sTCP:LISTEN

    輸出 *:8000 代表所有位址。127.0.0.1:8000 代表只有回送（loopback）位址。

  3. 如果映像檔內含 wget，可從容器內測試主機名稱。

    docker exec my-container wget -qO- http://host.docker.internal:8000

如何修正

  1. 在容器內，使用 host.docker.internal 而非 localhost。Docker Desktop 和 OrbStack 都支援這個名稱。

  2. 在 App 的設定中填入這個位址，例如透過環境變數。

    docker run -e API_URL=http://host.docker.internal:8000 my-image

  3. 使用 OrbStack 時，也可以改用主機網路模式。這樣在容器內就能透過 localhost 連到 Mac 上的服務。

    docker run --net host my-image

  4. 如果仍然無法連線，請檢查 macOS 防火牆設定。請參閱「macOS 防火牆阻擋傳入連線」。

使用 Kilobat

  1. Kilobat 的檢查是在 Mac 上執行，而不是在容器內。加上 --context container 即可取得要在容器內執行的指令。

    kilobat why http://localhost:8000 --context container

  2. 如果是雲端託管的服務要呼叫你的 Mac，請使用 --context provider。Kilobat 會指出 localhost 是私有位址，該服務連不到。

    kilobat why http://localhost:8000 --context provider

常見問題

host.docker.internal 在 Linux 上也能用嗎？

本頁只涵蓋 Mac。在 Docker Desktop for Mac 和 OrbStack 上，這個名稱會解析為主機。

為什麼 Safari 連得到服務，容器卻不行？

Safari 在 Mac 上執行，所以 localhost 就是 Mac。容器則有自己的 localhost。

資料來源

資料來源檢查日期：2026年10月29日。man 頁面為 macOS 內建版本；在終端機中用 man <name> 開啟。