推荐使用 host.docker.internal（Docker Desktop）或 --add-host=host.docker.internal:host-gateway（Linux），避免硬编码网关IP；因自定义网络网关地址不固定（如172.18.0.1），而 host-gateway 语义明确、兼容性强，确保容器稳定访问宿主机服务。
在 docker compose 开发环境中，容器默认运行在自定义桥接网络（user-defined bridge）中，与宿主机网络隔离。这意味着容器内无法用 localhost 或 127.0.0.1 访问宿主机服务（比如本地 mysql、redis、api 代理等），必须明确知道并使用宿主机在该网络中的可访问地址。
Linux 环境下：推荐用 --add-host 注入解析
Linux 原生 Docker Engine 不支持 host.docker.internal（除非升级到 20.10+ 并启用实验特性）。最稳定的方式是在 docker-compose.yml 中显式添加主机映射：
- 在服务配置中加入
extra_hosts：
- "host.docker.internal:host-gateway"
其中 host-gateway 是 Docker 内置关键字，会自动解析为宿主机在当前网络中的网关 IP（通常是 172.17.0.1 或自定义网桥的网关地址）。
- 这样容器内就能直接通过
http://host.docker.internal:3000或redis://host.docker.internal:6379连接宿主机服务； - 该方式兼容所有 Linux 发行版和 Docker 版本，无需依赖 DNS 或手动查 IP。
macOS / Windows（Docker Desktop）：直接用 host.docker.internal
Docker Desktop 原生支持这个特殊 DNS 名称，无需额外配置：
- 容器内执行
ping host.docker.internal可通； - 在应用配置中（如环境变量、连接字符串）直接写
host.docker.internal即可； - 它会自动解析为宿主机的正确地址，且对多网卡、DHCP 场景更鲁棒。
避免硬编码 172.17.0.1 的原因
虽然在默认 bridge 下宿主机网关常是 172.17.0.1，但在 Compose 中通常使用自定义网络（如 default 网络），其网桥 IP 可能不同（例如 172.20.0.1）：
- 用
ip route | grep default | awk '{print $3}'在容器内查，结果可能每次重建网络都变； - 硬编码 IP 会导致配置不可移植、CI/CD 失败、团队协作出错；
-
host-gateway和host.docker.internal是语义化方案，让意图清晰、行为确定。
不建议用 host 网络模式做开发隔离
虽然设置 network_mode: "host" 能让容器直接用 localhost 访问宿主机，但会破坏 Compose 的网络隔离设计：
- 容器失去独立端口空间，容易与宿主机其他服务冲突；
- 无法使用 Compose 内置 DNS（如服务名互访）；
- 不符合“开发即生产”原则，本地行为与容器化部署不一致。
