给容器补 hosts 记录
extra_hosts 在服务里追加 /etc/hosts 记录，用来把某个名字解析到指定地址。最常用的写法是把 host-gateway 映射成 host.docker.internal，让容器能访问宿主机上的服务；另一种是给内网系统域名指定固定 IP。记录在容器创建时写入，地址变化后需要重建容器，因此适合相对稳定的目标，不适合频繁变动的地址。
基本信息
| 字段 | extra_hosts 列表或映射形式 |
|---|---|
| 特殊值 | host-gateway 表示宿主机网关地址 |
| 生效时机 | 容器创建时写入 /etc/hosts |
| 解析优先级 | hosts 记录优先于 DNS 查询 |
典型使用场景
- 容器访问宿主服务：本地开发时连宿主上的数据库或 mock 服务
- 内网域名指到固定地址：某些系统没有内网 DNS，用 hosts 记录顶替
- 规避 DNS 改造：短期方案里把关键域名写死到容器，减少依赖
- 灰度切换：把某个域名临时指向新地址做验证
- 跨环境统一配置：不同环境的解析目标通过编排文件注入
配置与验证
配置与验证
services:
api:
image: app/api:1.4.2
extra_hosts:
- "host.docker.internal:host-gateway" # 指向宿主机
- "legacy.internal:10.0.0.8" # 内网系统固定地址
environment:
- UPSTREAM=http://host.docker.internal:9000
# 验证解析结果
# docker compose exec api getent hosts host.docker.internal记录类型与场景
| 写法 | 解析结果 | 适用场景 |
|---|---|---|
| host.docker.internal:host-gateway | 宿主机网关地址 | 容器访问宿主上的服务 |
| legacy.internal:10.0.0.8 | 固定 IP | 内网域名解析到指定设备 |
| 多值同名记录 | 按 hosts 顺序匹配 | 需要临时把域名切到新地址验证 |
host-gateway 需要较新的 Docker 版本与对应平台支持，老版本环境里要改用宿主真实地址。
与 DNS 解析同名冲突时以 /etc/hosts 为准，排查解析异常先看这里有没有残留记录。
容器访问宿主服务时，除了加 hosts 记录，还要确认宿主上的服务监听地址覆盖容器来源网段：只绑定 127.0.0.1 的宿主服务，容器即使解析到正确地址也连不上。
轮换地址或切换上游时，先改编排文件再重建服务，让解析结果与配置保持同一版本，避免运行中的容器仍在使用旧地址。