---
title: "從 Docker 容器連到 Mac 上的 localhost 服務 · Kilobat 指南"
url: "https://kilobat.app/zh-hant/guides/localhost-from-container.html"
description: "在容器內，localhost 指的是容器本身。要連到 Mac 上執行的資料庫、API 或模型伺服器，請使用 host.docker.internal。"
---

開發者

# 容器無法連到 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 防火牆阻擋傳入連線](https://kilobat.app/zh-hant/guides/macos-firewall-incoming.html)」。

## 使用 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。

## 資料來源

- [Docker Docs：Explore networking how-tos on Docker Desktop](https://docs.docker.com/desktop/features/networking/networking-how-tos/)
- [OrbStack Docs：Container networking](https://docs.orbstack.dev/docker/network)
- [OrbStack 說明文件：Host networking](https://docs.orbstack.dev/docker/host-networking)
- lsof(8)，macOS 27.2 內建的 man 頁面

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

## 相關指南

- [無法從 Mac 連到 Docker 容器](https://kilobat.app/zh-hant/guides/docker-container-from-mac.html): Mac 上的 Docker 會在 Linux 虛擬機器中執行容器。
- [macOS 防火牆阻擋傳入連線](https://kilobat.app/zh-hant/guides/macos-firewall-incoming.html): macOS 防火牆控制其他電腦主動連到你 Mac 的連線。
- [找出某個網站或 API 連不上的原因](https://kilobat.app/zh-hant/guides/recipes/why-cant-it-connect.html): 網路正常、只有某個位址失敗時，Kilobat 會逐層檢查。
- [Mac 上的連接埠已被占用](https://kilobat.app/zh-hant/guides/port-already-in-use.html): 同一個 TCP 連接埠和位址只能有一個處理程序在監聽。