---
title: "从 Docker 容器访问 Mac 上的 localhost 服务 · Kilobat 指南"
url: "https://kilobat.app/zh-hans/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` 表示仅限环回地址。
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-hans/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-hans/guides/docker-container-from-mac.html): Mac 上的 Docker 在 Linux 虚拟机中运行容器。
- [macOS 防火墙阻止传入连接](https://kilobat.app/zh-hans/guides/macos-firewall-incoming.html): macOS 防火墙控制其他电脑向 Mac 发起的连接。
- [找出某个网站或 API 连不上的原因](https://kilobat.app/zh-hans/guides/recipes/why-cant-it-connect.html): 互联网正常、唯独某个地址连不上时，Kilobat 会逐层进行检查。
- [Mac 上端口已被占用](https://kilobat.app/zh-hans/guides/port-already-in-use.html): 一个 TCP 端口和地址只能由一个进程监听。