在 Windows 上使用 Docker Desktop 的开发者，经常会遇到一个典型问题：宿主机上的快连明明工作正常，浏览器可以打开 Docker Hub，但在终端执行 docker pull 时却长时间卡住，最后提示超时；或者容器启动后，容器内部执行 apt update、pip install、npm install 时无法访问国外源。原因在于，Docker 的网络与宿主机是隔离的，Docker Desktop 运行在一个轻量级虚拟机中，容器又有自己的网络命名空间，默认不会继承 Windows 的系统代理设置。
要解决这个问题，需要分三层配置：Docker Desktop 自身（负责拉取镜像）、容器运行时（负责容器内访问网络）、构建过程（负责 docker build 时的依赖下载）。快连官网（kenlandd.com.cn）技术团队将在本文中，从 Docker 网络结构讲起，逐步给出三层的代理配置方法、验证步骤和常见问题排查，帮助你在 Docker 开发环境中顺畅使用快连。
一、先理解Docker的网络结构
在 Windows 上，Docker Desktop 并不是直接运行在 Windows 内核上，而是运行在一个由 WSL2 或 Hyper-V 支撑的 Linux 虚拟机中。这个虚拟机有自己的网络接口，容器又运行在这个虚拟机内部，拥有独立的网络命名空间。因此，网络请求的路径大致是：容器 → Docker 虚拟网络 → Docker Desktop 虚拟机 → Windows 宿主机 → 快连节点 → 互联网。
每一层都可能需要代理配置：
- Docker Desktop 虚拟机：负责
docker pull拉取镜像，需要配置 Docker daemon 的代理。 - 容器运行时：容器内部访问网络，需要给容器设置环境变量或在容器内配置代理。
- 构建过程：
docker build时执行的 RUN 指令，需要把代理参数传入构建上下文。
这三层相互独立，只配置其中一层，往往只能解决一部分问题。比如只配置了 Docker Desktop 代理，docker pull 会变快，但容器内 pip install 仍然超时。
二、确认快连代理地址与端口
在配置之前，先确认快连的本地代理端口。打开快连电脑版，进入“设置”或“高级设置”，查看“本地代理端口”或“HTTP 代理端口”，常见端口有 7890、1080、8080 等。记下端口号。
同时，建议在快连设置中开启“允许局域网连接”。Docker Desktop 虚拟机访问 Windows 宿主机时，使用的是虚拟网卡地址，不是 127.0.0.1。开启允许局域网连接后，虚拟机才能通过宿主机 IP 访问快连代理。如果你还没有安装最新版快连，可以前往快连下载页面获取最新客户端，新版本对局域网访问和代理端口的显示更清晰。
接下来需要获取 Windows 宿主机在 Docker 虚拟机视角下的 IP。对于 WSL2 后端，可以在 WSL2 中执行 cat /etc/resolv.conf | grep nameserver 获取；对于 Hyper-V 后端，可以在 Docker Desktop 设置中查看网络信息。通常，Docker Desktop 虚拟机可以通过 host.docker.internal 这个特殊域名访问宿主机，这是最方便的方式，无需手动查 IP。
三、配置Docker Desktop自身代理（拉取镜像）
Docker Desktop 的代理配置位于“Settings → Resources → Proxies”。在这里可以设置 HTTP 和 HTTPS 代理。填写方式如下：
- HTTP Proxy：
http://host.docker.internal:7890（端口替换为快连实际端口） - HTTPS Proxy：
http://host.docker.internal:7890 - No Proxy：可以填写
localhost,127.0.0.1,*.local，避免本地地址走代理。
填写后点击“Apply & Restart”，Docker Desktop 会重启生效。之后执行 docker pull hello-world 测试，如果能正常拉取，说明 daemon 代理生效。
如果使用 host.docker.internal 仍然无法连接，可以尝试填写 Windows 宿主机的实际局域网 IP，例如 http://192.168.1.100:7890。可以在 Windows 命令提示符中执行 ipconfig 查看当前网卡的 IPv4 地址。注意，如果宿主机 IP 变化，需要同步更新代理设置。
四、配置容器运行时代理（容器内访问网络）
容器内部访问网络时，不会自动读取 Docker Desktop 的代理设置。需要在运行容器时通过环境变量传入代理。常见方式有两种：
1. 使用 docker run 传入环境变量
在执行 docker run 时，添加 -e 参数：
docker run -it \ -e http_proxy=http://host.docker.internal:7890 \ -e https_proxy=http://host.docker.internal:7890 \ -e HTTP_PROXY=http://host.docker.internal:7890 \ -e HTTPS_PROXY=http://host.docker.internal:7890 \ -e no_proxy=localhost,127.0.0.1 \ ubuntu:latest bash
进入容器后，执行 curl -I https://www.google.com 或 apt update 测试。如果返回正常，说明容器内代理生效。
2. 在 Dockerfile 中设置环境变量
如果希望镜像构建后就带上代理配置，可以在 Dockerfile 中添加：
ENV http_proxy=http://host.docker.internal:7890 ENV https_proxy=http://host.docker.internal:7890 ENV HTTP_PROXY=http://host.docker.internal:7890 ENV HTTPS_PROXY=http://host.docker.internal:7890
但要注意，这样构建出的镜像会把代理地址固化进去，不适合分发。更推荐的做法是在运行时通过 -e 或 docker-compose 传入，保持镜像干净。
3. 使用 docker-compose 统一配置
在 docker-compose.yml 中，可以为服务添加 environment：
services:
app:
image: ubuntu:latest
environment:
- http_proxy=http://host.docker.internal:7890
- https_proxy=http://host.docker.internal:7890
- HTTP_PROXY=http://host.docker.internal:7890
- HTTPS_PROXY=http://host.docker.internal:7890
- no_proxy=localhost,127.0.0.1
这样所有通过 compose 启动的容器都会带上代理设置，管理起来更方便。
五、配置docker build过程中的代理
docker build 执行 RUN 指令时，默认不会继承宿主机的代理环境变量。需要在构建时通过 --build-arg 传入，并在 Dockerfile 中声明。示例：
# Dockerfile ARG http_proxy ARG https_proxy ARG HTTP_PROXY ARG HTTPS_PROXY RUN apt update && apt install -y curl
构建命令：
docker build \ --build-arg http_proxy=http://host.docker.internal:7890 \ --build-arg https_proxy=http://host.docker.internal:7890 \ --build-arg HTTP_PROXY=http://host.docker.internal:7890 \ --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \ -t myapp .
这样构建过程中的 apt、pip、npm 等命令就会走快连代理。注意，构建完成后代理参数不会保留在最终镜像中，比较安全。
六、验证代理是否生效
配置完成后，建议分层验证：
- Docker daemon 代理：执行
docker pull hello-world，观察拉取速度。也可以在 Docker Desktop 的日志中搜索 proxy 关键词，确认代理配置已加载。 - 容器内代理：进入容器执行
env | grep -i proxy，确认环境变量已设置；再执行curl -I https://www.google.com，确认能访问。 - 构建代理：在 Dockerfile 中添加
RUN curl -I https://www.google.com，构建时观察是否成功。如果失败，检查 build-arg 是否传入。 - IP 查询：在容器内执行
curl ipinfo.io，查看出口 IP 是否为快连节点 IP。
如果某一层验证失败，先确认该层的代理配置是否正确，再检查快连是否处于连接状态，以及 Windows 防火墙是否放行了来自 Docker 虚拟网卡的请求。关于端口和防火墙的排查，可以参考《快连电脑版代理端口占用排查指南》。
七、常见问题与排查
1. host.docker.internal 无法解析
在部分 Docker Desktop 版本或 Linux 容器中，host.docker.internal 可能无法解析。可以在运行容器时添加 --add-host=host.docker.internal:host-gateway 参数，手动映射宿主机地址。或者在 docker-compose 中添加 extra_hosts。
2. 容器内代理设置后仍然无法访问
首先确认快连已连接且允许局域网访问。其次确认环境变量大小写都设置了，部分工具只认小写。再次确认 no_proxy 没有误包含目标域名。最后检查容器内的 DNS 解析是否正常。如果 DNS 异常，可以在容器中手动指定 DNS，或使用 --dns 参数。
3. docker build 时 ARG 不生效
ARG 必须在 FROM 之后、使用它的 RUN 之前声明。如果使用了多阶段构建，每个阶段都需要重新声明 ARG。另外，构建时如果使用了 --no-cache，确保 build-arg 拼写正确。
4. 配置代理后本地服务访问异常
代理设置后，容器访问 localhost 或内网服务也可能被转发到代理，导致连接失败。可以通过 no_proxy 排除本地和内网地址，例如 localhost,127.0.0.1,192.168.0.0/16,10.0.0.0/8。关于分流和例外的思路，可以参考《快连电脑版分域名分流规则编写入门》。
5. Docker Desktop 重启后代理失效
检查 Docker Desktop 的代理设置是否保存成功。部分版本在升级后会重置代理配置，需要重新填写。建议把代理配置记录下来，升级后快速恢复。
6. 使用 TUN 模式时 Docker 网络异常
快连的 TUN 模式会修改系统路由，可能影响 Docker Desktop 虚拟机的网络。如果发现 Docker 在 TUN 模式下无法拉取镜像或容器无法联网，可以切换到系统代理模式，或为 Docker 相关网卡添加例外。关于两种模式的区别，可以参考《快连电脑版系统代理与TUN模式区别说明》。
八、最佳实践与注意事项
- 分层配置：daemon、容器、构建三层分别配置，不要指望一层解决所有问题。
- 优先使用 host.docker.internal：避免宿主机 IP 变化导致代理失效。
- 容器代理用环境变量：不要把代理地址固化到镜像中，保持镜像可移植。
- 构建时用 build-arg：临时传入代理，构建完成后不残留。
- 配置 no_proxy：排除本地和内网地址，避免本地服务异常。
- 保持客户端更新：新版本可能优化局域网访问和代理兼容性，建议从快连下载页面获取最新版本。
- 记录配置：把 Docker 代理配置记录在项目文档中，换机或团队协作时快速复用。
九、总结
Docker 环境下的快连代理配置，难点不在于配置本身，而在于理解 Docker 的网络分层。Docker Desktop 虚拟机、容器运行时、构建过程各自独立，需要分别配置。只要掌握 host.docker.internal 的用法、环境变量的传入方式和 build-arg 的机制，就能让镜像拉取、容器内访问和构建过程都顺畅走快连。
如果你在配置过程中遇到问题，或者想了解更多快连使用技巧，欢迎访问快连技术博客，或联系快连官方客服获取支持。快连技术团队会持续输出实用教程，帮助大家在 Windows、WSL2、Docker 等开发环境中都能稳定使用快连。