如何在启动容器时使用 --add-host 注入特定的主机记录条目指南

--add-host参数可直接向容器/etc/hosts添加静态映射，语法为docker run --add-host=域名:IP，支持多次使用添加多条，IPv6可用，但不适用于host网络模式，且挂载自定义hosts文件会完全覆盖默认内容。

直接用 --add-host 就能往容器的 /etc/hosts 里加一行映射，不需要进容器手动改，也不依赖 DNS。关键是要写对格式、注意作用范围和潜在冲突。

基本用法：一条命令加一条记录

语法很简单：docker run --add-host=域名:IP。冒号不能省略，前后不加空格，域名和 IP 都不能带引号（除非含特殊字符，此时用单引号包裹整个参数）。

• docker run --add-host=api.example.com:10.0.2.5 -it nginx:alpine
• 启动后进容器执行 cat /etc/hosts，能看到新增行：10.0.2.5 api.example.com
• 支持 IPv6，例如：--add-host=db.local:2001:db8::1

一次添加多个主机映射

重复使用 --add-host 参数即可，顺序无关，Docker 会按顺序追加到 /etc/hosts 开头部分。

• docker run --add-host=auth.service:172.18.0.10 --add-host=cache.service:172.18.0.11 --add-host=logs.internal:192.168.100.20 -d myapp
• 注意：不要用逗号或换行分隔；每个 --add-host 必须独立出现

常见问题与避坑点

加了却不起作用？大概率是这几个原因：

• 镜像自身启动脚本覆盖了 /etc/hosts（比如某些 Alpine 基础镜像在 entrypoint 中重写 hosts），建议优先检查容器内实际文件内容
• Docker 版本低于 1.10 —— 该参数从 1.10 开始支持，运行 docker version 确认
• 用了错误格式，如 --add-host api.example.com=10.0.2.5（等号错）、--add-host "api.example.com:10.0.2.5"（多余引号干扰解析）
• 容器使用了 --network host 模式 —— 此时容器共享宿主机网络命名空间，--add-host 不生效

替代方案：需要持久化或动态更新时

如果映射条目多、经常变，或者要复用同一份 hosts 配置，硬编码多个 --add-host 就不太方便。这时推荐挂载自定义 hosts 文件：

• 准备一个本地文件 my-hosts，内容如：
  

  10.0.3.10 db.prod<br>10.0.3.20 api.staging

• 启动时用 -v $(pwd)/my-hosts:/etc/hosts:ro 挂载（注意加 :ro 防止容器误写）
• 该方式会完全替换容器默认生成的 /etc/hosts，包括 Docker 自动添加的容器 ID 和 gateway 条目，需自行保留必要项