参数是干什么的
docker run --add-host 把额外的名称到 IP 映射写进容器的 /etc/hosts。它适合让容器访问宿主机上的服务，或指向某个固定地址，免去修改宿主 DNS。host-gateway 是表示宿主机的特殊值，写成 host.docker.internal:host-gateway 就能稳定访问宿主服务，不必写死宿主 IP。
基本信息
| 用途 | 向容器注入 hosts 记录 |
|---|---|
| 语法 | --add-host 名称:IP，可重复指定多条 |
| 特殊值 | host-gateway 表示宿主机地址 |
| 生效时机 | 容器创建时写入 /etc/hosts |
| 适用平台 | Docker Engine（host-gateway 需较新版本支持） |
典型使用场景
- 容器访问宿主上运行的服务，避免写死宿主 IP
- 指向内网固定地址，临时替代 DNS
- 本地开发环境模拟线上域名解析
- 排查解析异常时先看 /etc/hosts 里的条目
- 让容器内应用连到指定实例做验证
注入与核对
注入与核对
docker run -d --name web --add-host api.internal:10.0.0.8 --add-host host.docker.internal:host-gateway nginx:1.27
docker exec web cat /etc/hosts # 确认记录已写入
docker exec web getent hosts host.docker.internal # 验证解析结果
docker inspect -f '{{json .HostConfig.ExtraHosts}}' web # 核对容器配置中的条目写法与含义
| 写法 | 含义 | 注意 |
|---|---|---|
| --add-host 名称:IP | 写入一条 hosts 记录 | 可重复指定多条 |
| host-gateway | 代表宿主机地址的特殊值 | 与固定名称搭配使用最稳 |
| /etc/hosts | 容器内实际生效位置 | 内容在创建时生成 |
| ExtraHosts | inspect 中的对应字段 | 排查时可核对配置 |
hosts 条目在创建容器时写入，运行期间无法修改，需要改地址只能重建容器。
当 hosts 条目与真实 DNS 同名时会优先生效，排查解析异常时先检查这一段内容。
使用建议与边界
- 访问宿主服务优先用表示宿主机的特殊值，避免写死会变化的地址
- 条目只在创建时写入，运行中改地址必须重建，规划时留好变更窗口
- 同名条目会覆盖真实解析结果，排查网络问题时先看这一段
- 这类记录适合少量固定映射，大量域名解析仍应交给正规的名称服务
- 把用到的条目写进编排文件，避免只存在于某次手工命令里
编排场景下可以把这些条目写进服务的额外主机字段，让配置随文件一起版本化，避免只留在某台机器的命令历史里。