--add-host 是 Docker docker run 命令中的一个非常实用的参数，用于在容器的 /etc/hosts 文件中手动添加主机名到 IP 地址的映射。这在需要自定义网络解析、调试或容器与外部服务通信时非常有用。
🔹 一、基本语法
docker run --add-host=HOSTNAME:IP [其他选项] <镜像名>
HOSTNAME：你想在容器内解析的主机名（例如：host.docker.internal、db.local、api.service等）。IP：该主机名对应的 IP 地址（如172.17.0.1、host-gateway等）。
🔹 二、作用原理
Docker 在启动容器时，会自动创建一个独立的网络命名空间。容器内的 /etc/hosts 文件默认包含一些基本条目（如 localhost、容器自身主机名等）。
使用 --add-host 后，Docker 会在容器启动前自动向 /etc/hosts 文件中追加一条记录，例如：
172.17.0.1 host.docker.internal
这样，容器内的应用程序就可以通过 host.docker.internal 直接访问宿主机上的服务，而无需依赖 DNS 或硬编码 IP。
🔹 三、常用场景
✅ 1. 容器访问宿主机服务（最常见）
比如宿主机运行了 MySQL、Redis 或 API 服务，容器需要访问它。
docker run --add-host=host.docker.internal:host-gateway \
-it myapp:latest
在容器内：
ping host.docker.internal curl http://host.docker.internal:3000/api
✅ 2. 模拟域名解析（开发/测试环境）
用于测试某些域名行为，比如模拟 api.myapp.com 指向某个测试服务器。
docker run --add-host=api.myapp.com:192.168.1.100 \
myapp:latest
✅ 3. 避免 DNS 依赖或解决 DNS 解析问题
在某些网络环境中，DNS 可能不稳定或被污染，使用 --add-host 可强制指定 IP。
docker run --add-host=github.com:140.82.121.4 \
alpine ping github.com
✅ 4. 多容器通信（替代 link，简单场景）
虽然推荐使用自定义网络和 Docker DNS，但在简单场景下也可用：
# 假设 db 容器 IP 是 172.17.0.10
docker run --add-host=db:172.17.0.10 myapp
🔹 四、特殊值：host-gateway
从 Docker 20.10 开始，支持一个特殊关键字：
--add-host=host.docker.internal:host-gateway
host-gateway会被 Docker 自动解析为宿主机的内部网关 IP（通常是docker0网桥的地址，如172.17.0.1）。- 这个值跨平台兼容，特别适合 Linux 环境下替代手动写死 IP。
⚠️ 注意：
host-gateway需要 Docker 20.10+ 和dockerd正确配置支持。
🔹 五、查看效果（验证）
进入容器后，可以查看 /etc/hosts 是否添加成功：
docker exec -it <容器名> cat /etc/hosts
输出示例：
127.0.0.1 localhost
172.17.0.2 f1a2b3c4d5e6
172.17.0.1 host.docker.internal # ← 这是你添加的
🔹 六、限制与注意事项
| 注意项 | 说明 |
|---|---|
| ❌ 不支持 DNS 动态更新 | 添加的是静态 hosts 记录，不支持 TTL 或动态刷新。 |
❌ 不能覆盖 localhost |
试图用 --add-host=localhost:xxx 通常无效，系统保留。 |
| ❌ 多个 --add-host | 可以多次使用，每个添加一条记录。 |
| ✅ 安全性 | 仅影响容器内部解析，不影响宿主机或其他容器。 |
| ✅ 与自定义网络共存 | 可与 docker network 一起使用，优先级高于 DNS。 |
🔹 七、多个主机映射示例
docker run \
--add-host=host.docker.internal:host-gateway \
--add-host=db.prod:10.0.0.10 \
--add-host=api.local:192.168.1.5 \
myapp:latest
🔹 八、与 docker-compose 的对应关系
在 docker-compose.yml 中，等价写法是 extra_hosts：
services:
app:
image: myapp:latest
extra_hosts:
- "host.docker.internal:host-gateway"
- "db.local:10.0.0.10"
✅ 总结
| 特性 | 说明 |
|---|---|
| 用途 | 向容器的 /etc/hosts 添加自定义主机名解析 |
| 适用场景 | 访问宿主机、模拟域名、调试、绕过 DNS |
| 推荐用法 | --add-host=host.docker.internal:host-gateway（Linux 宿主访问） |
| 优点 | 简单、高效、无需修改应用代码 |
| 替代方案 | 自定义 DNS、修改应用配置、使用 --network=host（不推荐） |
💡 提示：如果你在容器中需要“访问本机服务”，记住：容器的“本机” ≠ 宿主机。要用
--add-host显式告诉它“谁是宿主机”。