Docker Desktop 怎样为开发环境配置代理

开发机浏览器能打开网页，不代表 Docker Desktop 里的镜像拉取和容器请求也能联网。配置代理时最容易犯的错，是只改了 Desktop 应用代理，却没有为 docker pull 选择对应的 Containers 代理。正确做法是先分清两类流量，再到 Settings > Resources > Proxies 配置并保存。

官方地址：https://docs.docker.com/desktop/settings-and-maintenance/settings/

本文中的界面图是原创说明图，命令和日志片段是用于理解配置边界的示例，不代表在本文环境中实际运行过。

先判断：你要代理的是哪一类流量

Docker Desktop 把代理分成两个作用范围。Docker Desktop proxy主要负责登录、Desktop 应用、Docker CLI 和扩展等主机级流量；当没有单独配置 Containers proxy 时，它还可以作为镜像拉取的回退代理。Containers proxy主要负责 docker image pull，使用 Compose 拉取镜像时也要关注这一层。

因此，不要先修改宿主机全局代理或 daemon.json。Docker Desktop 的设置页面才是本教程的入口；直接使用 Docker API 的插件或工具，可能仍然需要单独设置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。

进入 Resources > Proxies，选择正确的设置项

打开 Docker Desktop 设置，进入 Resources，再选择 Proxies。如果只是让 Desktop 跟随公司或系统代理，优先选择 System proxy；如果系统没有稳定的自动发现结果，再选择 Manual configuration，填写明确的 HTTP 或 HTTPS 代理地址。

界面中两个区域不要混为一谈：Desktop proxy 解决应用和 CLI 的主机流量，Containers proxy 决定镜像拉取是否走代理。若目标只是拉取私有仓库或公共仓库镜像，至少要确认 Containers proxy 没有保持在 No proxy。

填写 HTTP、HTTPS 与 NO_PROXY

手动配置时，HTTP 和 HTTPS 字段应使用带协议和端口的地址，例如 http://proxy.example:3128。不要只填主机名，也不要把带路径的网页地址当成代理地址。NO_PROXY 用来列出不应经过代理的主机、域名或网段，例如公司内网服务、回环地址和内部注册中心。

# 下面是格式示例，不包含真实账号、密码或企业地址。
HTTP:  http://proxy.example:3128
HTTPS: http://proxy.example:3128
NO_PROXY: localhost,127.0.0.1,*.internal.example

如果代理服务要求认证，Docker Desktop 可能弹出凭据提示，并把凭据交给操作系统的凭据存储管理。不要把用户名和密码直接写进文章、脚本或共享的 Compose 文件。代理地址里即使包含特殊字符，也应优先使用界面提供的凭据流程。

配置完成后点击 Apply 或页面对应的保存按钮，等待 Desktop 完成重新加载。保存前先记下原来的代理模式，方便配置不合适时回退到 System proxy 或 No proxy。

保存后怎样判断代理真的生效

验证时按“镜像拉取—容器请求—日志线索”三层看，不要只以浏览器能否联网作为结论。下面命令仅用于展示判断顺序，输出内容是示例。

# 先确认当前 Docker CLI 能连接到 Desktop 引擎。
docker version

# 用一个需要访问注册表的动作观察镜像拉取是否能完成。
docker pull alpine:latest

# 启动一个短生命周期容器，观察容器内的 DNS 和 HTTP 请求是否符合预期。
docker run --rm alpine:latest sh -c 'wget -qO- https://example.com || exit 1'

如果 docker version 正常、docker pull 失败，重点回到 Containers proxy；如果镜像能拉取而容器请求失败，继续检查容器网络、代理是否覆盖容器出站流量以及 NO_PROXY 是否把目标错误地排除了。

Docker Desktop 的主机代理日志通常可在系统对应的 host 日志目录找到，官方 FAQ 给出的重点文件名是 httpproxy.log。日志中如果出现代理模式、HTTP_PROXY 或 HTTPS_PROXY 的记录，可用来判断 Desktop 采用的是系统代理还是手动代理。

# macOS 示例：只查看 Docker Desktop host 日志目录中的代理日志。
tail -n 80 "$HOME/Library/Containers/com.docker.docker/Data/log/host/httpproxy.log"

# Windows 示例：PowerShell 中按实际用户目录查看日志文件。
Get-Content "$env:LOCALAPPDATA\Docker\log\host\httpproxy.log" -Tail 80

如果命令路径因平台或版本不同而不存在，不要把“找不到日志文件”直接等同于代理失效；先在 Docker Desktop 的诊断或日志入口确认当前日志目录，再结合最近一次拉取时间判断。

几个容易忽略的边界

• PAC 与自动发现：系统代理或静态 PAC 可以被 Docker Desktop 读取，但只依赖 WPAD 自动发现并不稳妥；企业环境更适合提供明确的静态 PAC 地址或代理地址。
• 插件和外部工具：直接使用 Docker API 的 CLI 插件、构建工具或脚本，可能不读取 Desktop 设置，需要在它们自己的进程环境中配置 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。
• 平台认证差异：Windows 对部分 Basic、NTLM 和 Kerberos 场景的支持与 macOS 不同；如果认证协商失败，优先向代理管理员确认认证方式，不要反复切换地址格式。
• 回退顺序：先把 Containers proxy 设为与 Desktop proxy 相同，再单独测试镜像拉取；确认作用范围后，再按需要拆分成不同的 HTTP、HTTPS 或旁路域名配置。

常见问题

为什么浏览器可以联网，docker pull 还是超时？

浏览器使用的是自己的系统代理链路，而 docker pull 由 Docker Desktop 的 Containers proxy 处理。先在 Resources > Proxies 检查 Containers proxy 的模式、代理地址和仓库域名是否被 NO_PROXY 错误排除。

Docker Desktop 代理设置和 daemon.json 是一回事吗？

不是。Docker Desktop 有自己的代理设置和内部网络路径，不能把普通 Linux Engine 的配置方式直接套过来。先按 Desktop 官方设置页面完成配置，再处理独立引擎或外部工具的代理环境变量。

应该选 System proxy 还是 Manual configuration？

系统代理稳定、能覆盖当前网络时选 System proxy；需要固定代理地址、明确旁路域名或排查 PAC 行为时选 Manual configuration。选择后都要用镜像拉取和日志线索做一次范围判断。

总结一下：Docker Desktop 配代理的关键不是把一个地址填进去，而是先区分 Desktop proxy 和 Containers proxy。进入 Resources > Proxies 后选择合适模式，正确填写 HTTP、HTTPS 与 NO_PROXY，保存后分别观察 docker pull、容器请求和 httpproxy.log，才能知道问题发生在主机流量、镜像拉取还是容器网络这一层。