Docker pull 时出现 DNS 解析超时错误
本文适用于：
- • Docker 20+ / 24+
- • 国内网络环境
- • Windows WSL / Docker Desktop 用户
- • Docker 使用的 DNS 服务器无法访问外网
- • 遇到 DNS 解析超时错误
⚠️ 重要提示
这是 Docker 使用的 DNS 服务器无法访问外网导致的，不是镜像仓库的问题。
解决方案优先级：
- ✅ 方案 1：配置 Docker 公共 DNS（推荐，适用于所有系统）
- ✅ 方案 2：修复 WSL/Docker Desktop DNS（Windows 特有）
- ✅ 方案 3：使用 hosts 文件（临时方案）
✅ 推荐做法
在 /etc/docker/daemon.json 中配置公共 DNS（223.5.5.5、114.114.114.114）。Windows WSL 用户需要额外修改 /etc/resolv.conf 并禁止自动重置。
当您在拉取镜像时遇到 DNS 解析超时错误，Docker 无法解析镜像仓库域名，导致 docker pull 无法正常工作。
错误示例
错误含义
核心报错信息：
这是 DNS 解析超时错误。Docker 尝试向本地 DNS 服务器（172.27.32.1:53）发送域名解析请求，但在超时时间内没有收到响应。
简而言之：Docker 客户端无法解析域名 → 镜像仓库地址解析失败 → docker pull 无法进行
常见原因
| 原因类型 | 说明 |
|---|---|
| 1️⃣ Docker DNS 不可用 | Docker 默认使用宿主机的 DNS，但 WSL 或 Docker Desktop 内部虚拟网卡（如 172.27.32.1）的 DNS 无法访问外网 |
| 2️⃣ 宿主机 DNS 配置错误 | /etc/resolv.conf 配置不正确或指向的 DNS 服务器无响应 |
| 3️⃣ 域名解析问题 | 自定义域名（如 *.xuanyuan.run）在公网 DNS 中无法正确解析 |
| 4️⃣ 网络干扰 | 防火墙、公司网络策略或代理工具阻断了 DNS 请求 |
解决方案
✅ 方案 1：在 Docker 配置中手动指定公共 DNS
步骤 1：编辑 Docker 配置文件（Linux 通常位于 /etc/docker/daemon.json）
步骤 2：添加或修改为以下内容：
步骤 3：保存后重启 Docker 服务
步骤 4：重新尝试拉取镜像
✅ 方案 2：验证域名解析并配置 hosts（如果 DNS 无法解析）
步骤 1：在宿主机或容器中测试域名解析
如果超时或返回 SERVFAIL，说明 DNS 确实存在问题。
步骤 2：可以尝试使用本地 hosts 文件解析（临时方案）
添加一行（请替换为实际的 IP 地址）：
保存后再次尝试拉取镜像
✅ 方案 3：修复 Docker Desktop / WSL 网络（Windows 常见问题）
如果您在 Windows 下运行 Docker（特别是 WSL2 模式），DNS 默认走虚拟网卡（172.27.x.x），容易出错。
步骤 1：检查 WSL 的 DNS 配置
如果看到类似 nameserver 172.27.32.1，说明是 WSL 的内部 DNS。
步骤 2：手动修改 DNS 为公共 DNS
步骤 3：禁止 WSL 自动重置 resolv.conf
编辑 /etc/wsl.conf：
添加以下内容：
步骤 4：重新启动 WSL（在 PowerShell 中执行）
✅ 方案 4：检查网络连通性
使用以下检查点验证网络状态：
| ✅ | nslookup xxx.xuanyuan.run 能解析域名 |
| ✅ | curl https://xxx.xuanyuan.run/v2/ 能连上 |
| ✅ | Docker 配置了公共 DNS（223.5.5.5、114.114.114.114） |
| ⚠️ | 若仍超时，检查宿主机防火墙、代理设置 |
💡 总结：
- ✅ DNS 解析超时通常是 Docker 使用的 DNS 服务器无法访问外网导致
- ✅ 最直接的解决方法是在
/etc/docker/daemon.json中配置公共 DNS（223.5.5.5、114.114.114.114） - ✅ Windows WSL 用户需要特别注意修改
/etc/resolv.conf并禁止自动重置 - ✅ 确保网络畅通、防火墙未阻断 DNS 请求（UDP 53 端口）
本文由「xuanyuan.cloud」维护
专注国内 Docker / 镜像 / Registry 网络问题
内容基于真实用户环境与实测