在宿主机上运行数据库、缓存或调试接口，再让 Docker 容器中的应用连接它，是开发环境中的常见场景。很多人把连接地址写成 localhost 或 127.0.0.1 后，却只得到 “Connection refused” 或连接超时。问题通常不在端口映射，而在于容器和宿主机拥有不同的网络环境。🔍
一、为什么容器内的 localhost 访问不到宿主机
在默认的 bridge 网络模式下，容器拥有独立的网络命名空间，包括自己的网卡、IP 地址、路由表和回环接口。因此，容器中的 localhost 指向容器自身，而不是运行 Docker 的宿主机。假设宿主机的 8080 端口运行着一个 API，而容器内没有程序监听 8080，那么访问 来源链接 自然会失败。
还要区分两个方向：宿主机访问容器服务时，通常使用端口发布，例如 -p 8080:80；容器访问宿主机服务时，则需要一个从容器网络可达的宿主机地址。Docker 的 bridge 网络会在提供网络隔离的同时，通过网桥和相关路由处理容器流量，具体机制可参考 Docker Bridge 网络文档。
二、先判断故障发生在哪一层
建议按照“服务监听、名称解析、网络连通、访问控制”的顺序逐层检查，避免一看到报错就反复修改应用配置。🧭
- 确认宿主机服务确实运行：在宿主机执行 curl 来源链接 ss -lntp、netstat 等工具检查目标端口。
- 检查监听地址：如果服务只监听 127.0.0.1，它通常只接受宿主机回环接口上的连接。容器通过网桥访问时，应根据实际安全要求将服务监听到宿主机可达接口，常见测试配置为 0.0.0.0。
- 检查容器内解析结果：进入容器后执行 getent hosts host.docker.internal，确认名称能够解析。
- 测试 TCP 或 HTTP：使用 curl、wget 或 nc 直接访问目标地址和端口，从而排除应用框架、数据库驱动及连接池配置的影响。
- 检查防火墙与认证规则：连接超时通常更接近路由或防火墙问题；连接被拒绝通常意味着地址可达，但目标端口没有监听或主动拒绝连接。
三、使用 host.docker.internal 访问宿主机
Docker Desktop 提供了特殊 DNS 名称 host.docker.internal，它会解析到宿主机的内部可达地址。应用配置可以把原来的 localhost 改成该名称，例如访问宿主机 8080 端口时使用：
来源链接
在 Docker Desktop 环境中，这个名称通常可以直接使用。官方还提供 gateway.docker.internal，用于解析 Docker 虚拟机的网关地址，相关说明和连接示例可查看 Docker Desktop 网络指南。
四、Linux 上配置 host-gateway
在 Linux Docker Engine 环境中，如果容器无法解析 host.docker.internal，可以在启动容器时添加一条主机名映射。host-gateway 是 Docker 能够识别的特殊值，启动时会被转换为容器访问宿主机所使用的网关地址，因此比硬编码某个网桥 IP 更便于迁移。⚙️
docker run 配置
docker run --rm \
--add-host=host.docker.internal:host-gateway \
your-image
启动后可以进入容器检查：
getent hosts host.docker.internal
curl -v 来源链接
Docker Compose 配置
使用 Compose 时，可通过 extra_hosts 写入等效规则：
services:
app:
image: your-image
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
SERVICE_URL: "http://host.docker.internal:8080"
修改配置后应重新创建容器，而不是只重启旧容器：
docker compose up -d --force-recreate
映射生效后，容器的 /etc/hosts 中通常可以看到 host.docker.internal 对应的地址。不过，成功解析只说明“找到了地址”，并不代表目标服务已经监听正确接口，也不代表防火墙一定允许访问。
五、配置后仍然失败怎么办
- Unknown host：检查 --add-host 或 extra_hosts 的缩进、拼写，并确认容器已经重新创建。
- Connection refused：核对端口号以及服务监听地址，特别注意服务是否仅绑定 127.0.0.1。
- Connection timed out：检查宿主机防火墙、Docker 网络规则、安全软件和 VPN 是否拦截了容器网段。
- 认证失败：说明网络大概率已经连通，应继续检查数据库用户允许的来源地址、密码、TLS 和访问控制列表。
- 代理干扰：若应用使用 HTTP_PROXY 或 HTTPS_PROXY，应把 host.docker.internal 加入 NO_PROXY，避免请求被错误转发到代理服务器。
排查时还可以执行 docker network inspect bridge 查看网络配置，但不要默认网关永远是某个固定 IP。自定义网络、Docker Desktop 虚拟机和不同安装方式都可能产生不同结果，这正是使用 host-gateway 而非硬编码地址的价值所在。
六、是否应该改用 host 网络模式
在 Linux 上，使用 --network host 可以让容器共享宿主机网络栈，此时容器中的 localhost 可以直接对应宿主机网络环境。不过该模式会降低网络隔离程度，而且端口发布参数不会像 bridge 模式那样生效，多个服务也更容易发生端口冲突。Docker 对其行为和平台支持有明确说明，可参考 Host 网络驱动文档。
因此，host 网络更适合确有性能要求、需要处理大量端口，或必须直接使用宿主机网络的场景。普通开发环境中，优先使用 bridge 网络配合 host.docker.internal 和 host-gateway，通常更清晰，也更容易维护。✅
总结
Docker 容器内 localhost 无法访问宿主机服务，本质上是网络命名空间隔离造成的正常现象。正确处理方式是先确认宿主机服务的监听地址和端口，再通过 host.docker.internal 建立稳定的访问名称；Linux 环境无法解析时，使用 --add-host=host.docker.internal:host-gateway 或 Compose 的 extra_hosts 完成映射。最后结合错误类型检查防火墙、代理和认证规则，通常就能快速定位问题，而无需依赖容易变化的固定网关 IP。
