“Docker 构建镜像一直卡在下载 Python”不知道你遇到这个问题的时候是什么状态docker build跑到某一行突然不动了进度条半天不走甚至直接失败报一堆“connection reset”“timeout”之类让人摸不着头脑的东西。我最早碰到这种情况是在一个临时机器上当时准备构建一个内部 Web 服务的基础镜像拉 Python 基础镜像就等了快半个小时最后超时。后来换了几种姿势才彻底解决今天就专门聊一聊这个场景Docker 构建镜像卡在下载 Python 的典型原因以及一套靠谱的排查和应对思路。我会从现象判断、配置修改、实际构建这三个层面展开最后把常见的坑列成清单。不管你是刚接触 Docker 还是已经踩了不少坑这篇都能帮你少走弯路。核心就一句话卡住通常不是“卡”本身而是源、网络、配置这三者里至少有一个没对齐。1. 先搞清楚“卡在下载 Python”到底卡在哪一步1.1 构建镜像的完整链路不是只有一个“下载动作”先说一个容易被忽略的点Docker 构建镜像并不是“下载一个 Python 就完事”这么简单。一个常见的基础镜像python:3.11-slim背后是一层一层的文件系统构建时会先拉取基础镜像的所有层再基于这些层执行你在Dockerfile里写的RUN、COPY、ADD这些指令。整个过程大致分成三个阶段拉取基础镜像也就是从镜像仓库把python:3.11-slim的各个层下载到本地。执行构建指令比如RUN pip install ...、RUN apt-get install ...这些指令内部也要联网会去官方源下载 Python 依赖包。提交镜像层每条指令执行完后Docker 会把文件系统的差异打包成一个新层。很多人说“构建镜像卡在下载 Python”很可能卡在第一步拉取基础镜像也可能卡在第二步pip install或系统包管理器在下载软件包。但这两种情况的排查方向完全不一样所以第一步是“定位”。我自己习惯在开搞之前先加一个空行把docker build的进度打出来观察到底卡在哪一行。比如这条命令docker build -t my-python-app:latest .输出里如果长时间停在类似Step 2/5 : RUN pip install -r requirements.txt这行那就是构建中途在pip install这里卡住了。如果连基础镜像的层都没拉完输出会停在Pulling python:3.11-slim这一阶段。1.2 从日志输出判断是“拉层慢”还是“执行慢”卡在拉层阶段最典型的现象是Pulling fs layer ... Waiting ... Downloading [ ] 65%然后百分比在某个数值上卡很久或者下载速度为 0。这种一般就是镜像仓库的连通性问题。卡在执行阶段现象则不同Step 3/5 : RUN pip install flask --- Running in 8e6f9b1c2a11 Get:1 http://deb.debian.org/debian bullseye InRelease [157 kB]或者干脆WARNING: Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone))这说明基础镜像已经拿到了但执行pip install时连 Python 官方的包下载地址pypi.org或系统源比如 Debian 的软件源出了问题。所以排查的第一步不是改配置而是看清楚卡在哪一个输出节点。这一点搞混了下面做的可能全是无用功。1.3 环境因素网络、DNS、代理都会造成“假下载慢”除了“源”本身的问题还有一些容易被忽略的外部因素。我遇到过的情况有DNS 解析缓慢或超时导致镜像域名或 PyPI 域名根本无法解析。代理设置不生效Docker daemon 不一定自动继承你的系统代理尤其是 Linux 下用systemd管理 Docker 时需要单独配置。公司内网对境外域名做了访问限制或者带宽本身就很差。这个自己可以通过一条简单的命令来测试docker pull python:3.11-slim如果这条命令也慢或失败那问题基本就锁定在“从镜像仓库拉取”这个环节。如果这条命令很快但构建到pip install才卡那基本可以断定是“Python 依赖下载”的问题。2. 从源头解决问题配置可用的镜像源和软件源2.1 用对基础镜像等于少踩一半的坑构建 Python 镜像最常用的是这三类基础镜像镜像标签优点缺点适合场景python:3.11功能全自带常见工具体积大构建慢本地测试、快速验证python:3.11-slim体积中等包管理器可用缺少一些编译工具部分包需自行安装生产环境常见选择python:3.11-alpine体积极小需要编译的包容易踩坑兼容性略差追求极致镜像体积的场景如果你不是对体积有硬性要求我建议优先用-slim。它比完整版少装了很多和运行无关的工具但保留了apt-get遇到缺系统库的情况可以直接装。-alpine虽然小但内部用的是musl libc而非glibc有些 Python 包在安装时可能需要现场编译反而更容易卡在“下载编译依赖”上。另外一个小技巧尽量指定具体的 Python 版本比如用python:3.11.7-slim而不是python:3.11-slim。这样能保证每次拉取的缓存一致避免因为上游滚动更新导致同样的Dockerfile构建出不同结果。2.2 在 Dockerfile 里切换 pip 源如果你是卡在pip install阶段处理方式非常直接把pip默认的源切换到可用的国内源。我一般是这样写的FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 先设置 pip 源再复制依赖文件 RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ \ pip config set global.trusted-host mirrors.aliyun.com COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, app.py]这里有个容易犯错的点很多新手的习惯是把requirements.txt放到最后再复制这样每改一次代码依赖就要重新安装一遍。正确做法是先复制依赖文件安装完依赖再复制源码。这样代码改动不会破坏依赖缓存重建镜像会快很多。如果你不想在Dockerfile里写死可以在构建时通过构建参数传入ARG PIP_INDEX_URLhttps://mirrors.aliyun.com/pypi/simple/ RUN pip install --index-url ${PIP_INDEX_URL} -r requirements.txt构建时指定docker build --build-arg PIP_INDEX_URLhttps://mirrors.aliyun.com/pypi/simple/ -t my-app .这样既不污染团队公共镜像的默认配置又能灵活切换源。2.3 系统级软件源也要同步处理很多 Python 包需要在镜像里安装一些系统库比如常见的gcc、libpq-dev、build-essential等。在Dockerfile里执行apt-get install时默认访问的是 Debian/Ubuntu 官方源在国内同样容易卡住。处理方式是在Dockerfile开头替换sources.listFROM python:3.11-slim RUN sed -i s|deb.debian.org|mirrors.aliyun.com|g /etc/apt/sources.list.d/debian.sources \ || sed -i s|deb.debian.org|mirrors.aliyun.com|g /etc/apt/sources.list \ apt-get update需要注意的是不同 Debian 版本改源的文件路径不一样。比如 Debian 11 及更早版本是/etc/apt/sources.list而 Debian 12 换成了/etc/apt/sources.list.d/debian.sources。所以在写sed命令时我用了||做了兜底确保两个路径都能覆盖到。如果是 Ubuntu 基础镜像则可能需要修改/etc/apt/sources.list把archive.ubuntu.com替换成国内镜像域名。3. 从根上解决给 Docker 配置一个能连通的镜像仓库3.1 修改 Docker Daemon 的 registry-mirrors卸掉“软件源”的问题之后还有一个更底层的坑拉取基础镜像本身很慢。这时候需要给 Docker 配置镜像加速器准确说是配置registry-mirrors。Docker 支持在/etc/docker/daemon.json里添加镜像仓库地址{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] }修改完之后重启 Docker 服务sudo systemctl restart docker执行完这个配置再次docker pull python:3.11-slim速度通常会有明显改善。但要注意镜像仓库地址随时可能不可用尤其是一些公共服务性质较强的地址所以不要写死一个多放几个备选。如果你用的是 Docker DesktopWindows 或 macOS操作路径不同打开 Docker Desktop - Settings - Docker Engine会有一个 JSON 编辑框把同样的registry-mirrors写进去后点击 “Apply Restart” 即可。3.2 Windows 环境下的特殊处理Windows 上跑 Docker Desktop除了上面的路径之外还要额外留意一个问题Docker Desktop 默认使用 WSL 2 后端而 WSL 2 里的网络栈和宿主机不完全一致。有时候你在 Windows 里能正常访问的镜像源在 WSL 2 里可能因为 DNS 配置或防火墙原因连不上。这种情况下一个比较实用的做法是检查 WSL 2 的 DNS 配置。在 WSL 2 里执行cat /etc/resolv.conf如果看到nameserver指向了一个奇怪的地址可以尝试临时将 DNS 改为公共 DNSsudo unlink /etc/resolv.conf sudo bash -c echo nameserver 223.5.5.5 /etc/resolv.conf不过这种修改在 WSL 2 重启后可能会被还原所以更推荐直接在 Docker Desktop 的设置里把需要的配置都写清楚让导航问题在容器构建阶段之前就解决。3.3 使用 BuildKit 和缓存来减少重复下载Docker 从 20.10 版本开始默认启用 BuildKit它对构建缓存的处理要比旧版本高效得多。我们可以利用这个特性来避免同一个项目反复从远端拉依赖。启用 BuildKit 的方式export DOCKER_BUILDKIT1如果系统还没默认开启可以在每次构建前加上这个环境变量。使用 BuildKit 的好处是它可以并行执行无关的构建步骤并且支持RUN --mounttypecache这样的语法让pip install的下载缓存挂载到本地构建一次之后下一次不同镜像、不同分支也能复用之前的缓存内容。举个例子RUN --mounttypecache,target/root/.cache/pip pip install --no-cache-dir -r requirements.txt这样设置之后第二次构建大概率会跳过下载直接使用之前的缓存数据基本不再出现“卡在下载 Python 包”的情况。4. 实操复盘一个极简 Python Flask 项目的完整构建过程理论讲了这么多下面用一个实际例子走一遍完整流程。就从最常见的Flask项目开始最后构建一个可直接运行的小型 Web 镜像。4.1 项目文件准备目录结构my-python-app/ ├── app.py ├── requirements.txt └── Dockerfileapp.py内容随意这里用最简单的from flask import Flask app Flask(__name__) app.route(/) def index(): return Hello from Dockerized Python if __name__ __main__: app.run(host0.0.0.0, port5000)requirements.txtflask3.0.0 gunicorn21.2.04.2 编写 Dockerfile我先给一个带国内源配置的完整版本然后解释每一步# 选择基础镜像slim 版本体积适中包含 apt 工具 FROM python:3.11-slim # 设置环境变量防止 Python 写入字节码缓存 ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 # 更换系统源针对 Debian 12 路径做处理 RUN sed -i s|deb.debian.org|mirrors.aliyun.com|g /etc/apt/sources.list.d/debian.sources \ || sed -i s|deb.debian.org|mirrors.aliyun.com|g /etc/apt/sources.list \ apt-get update \ apt-get install -y --no-install-recommends build-essential \ rm -rf /var/lib/apt/lists/* # 切换 pip 源 RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ \ pip config set global.trusted-host mirrors.aliyun.com # 设置工作目录 WORKDIR /app # 先复制依赖清单利用缓存 COPY requirements.txt . # 安装依赖使用 BuildKit 缓存 RUN --mounttypecache,target/root/.cache/pip pip install --no-cache-dir -r requirements.txt # 复制项目代码 COPY . . # 容器启动时执行的命令 CMD [gunicorn, --bind, 0.0.0.0:5000, app:app]4.3 关键步骤解读第一步的PYTHONDONTWRITEBYTECODE和PYTHONUNBUFFERED是 Python 容器里的两个经典环境变量。前者防止 Python 生成__pycache__目录污染镜像后者确保日志实时输出到终端不会因为缓存导致你看不到容器日志。第二步的sed命令用来换系统源。我在 Debian 12 上遇到过${...}/debian.sources路径的情况所以用||做了路径兜底。实际执行时你可以先运行docker run --rm python:3.11-slim cat /etc/apt/sources.list.d/debian.sources确认路径是否存在。第三步设置pip的全局源文件中后续所有pip install都会走国内源。这里我选择在镜像里写入pip config set相比于每次都在命令行加--index-url参数这种写法更干净也避免了参数过长。第四步使用--mounttypecache挂载 pip 缓存目录这个是我使用 Docker 近两年最受益的一个技巧。没有这一行每次重新构建时pip install都会重复下载遇到网络波动就疯狂重试有了缓存之后构建时间肉眼可见地缩短。4.4 构建命令与验证基础准备没问题之后执行构建DOCKER_BUILDKIT1 docker build -t my-python-app:latest .如果一切顺利最终输出会是这样Writing image sha256:xxxxxx... Successfully built xxxxxx Successfully tagged my-python-app:latest然后启动容器验证docker run -d -p 5000:5000 --name my-python-app my-python-app:latest curl http://localhost:5000返回Hello from Dockerized Python整个构建过程如果在网络条件正常的国内环境下通常在几分钟内完成。如果还是慢大概率是某个环节的镜像源仍然不对需要按前面的排查思路逐项检查。5. 常见问题排查与避坑清单5.1 卡在 Downloading 且进度条不动这种情况多数是拉取镜像层失败原因可能是被防火墙拦截连接被重置。镜像仓库地址本身不可用。Docker daemon 的 DNS 解析异常。处理方式先手动执行docker pull python:3.11-slim看看是否复现。检查/etc/docker/daemon.json是否存在内容是否合法。换一个可用的 registry mirror或者直接通过docker pull指定一个已知可用的仓库地址。5.2 构建时提示 Python 包找不到比如ERROR: Could not find a version that satisfies the requirement xxx这种情况和“下载慢”不同属于源配置不完整或者依赖名写错。我先检查对应的包名是否在 PyPI 存在其次检查requirements.txt里是否有拼写错误尤其是数字字符下划线之类的差异。有些包名在 PyPI 上用的是横线但在import时用下划线这是最常见的坑。5.3 pip 源配置不生效如果你在Dockerfile里使用了RUN pip install -r requirements.txt而在这条指令之前没有跑过pip config set那么 pip 仍然会从默认的官方源下载。排查方法是docker run --rm my-python-app pip config list看是否打印出你预期的global.index-url配置。如果没生效检查是否把pip config set写在了WORKDIR切换之后或者RUN的 shell 环境是否发生了切换。5.4 超时后反复重试这种情况通常表现为WARNING: Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone))...说明连接超时但重试机制还在继续。除了换源之外还可以给 pip 增加超时时间参数RUN pip install --timeout 60 -r requirements.txt但这只能治标不能治本。根源还是连接速度慢或连接不稳定想办法让连接变快才是正路。5.5 其他值得记录的小经验最后再分享几个我自己在实际操作中踩过的小点。第一点不要把.dockerignore当作可选项。如果你在项目目录里执行构建同时目录下有venv、.git、日志等文件它们会被全部发送到构建上下文导致构建变慢甚至失败。这是“看似卡住”里一个隐蔽的原因实际上不是下载慢而是发送上下文慢。建议在任何 Docker 项目里先加一个.dockerignore__pycache__/ *.pyc *.pyo *.pyd .Python venv/ .venv/ .env .git/ .gitignore *.log .DS_Store第二点构建容器化 Python 应用时一定要把pip install的缓存考虑进镜像构建缓存策略里。如果你没有用 BuildKit 的--mounttypecache那么建议至少保持“先复制requirements.txt再安装依赖最后复制源码”的层顺序否则源码一变整个依赖层全部失效。第三点网络好的时候也别太肆无忌惮。镜像体积和依赖体积过大不仅影响构建时间还会影响部署速度。如果生产环境带宽有限一个几百 MB 的镜像发布一次都是折磨。通过多阶段构建把编译依赖和运行依赖分开最终产物可以控制在很小的体积。比如这样# 第一阶段安装依赖 FROM python:3.11-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --prefix/install -r requirements.txt # 第二阶段运行时镜像 FROM python:3.11-slim WORKDIR /app COPY --frombuilder /install /usr/local COPY . . CMD [python, app.py]这个做法实际上是把“编译工具链”和“运行环境”隔离开用完之后不把build-essential这类大文件带进最终镜像算是生产环境一个比较稳的优化方向。写在最后遇到 Docker 构建卡在下载 Python不用慌也不用急着把责任推到网络头上。按这个顺序排查先确认卡在拉取镜像阶段还是安装依赖阶段再检查daemon.json的 registry mirror然后依次处理系统源和 pip 源最后用 BuildKit 缓存优化后续构建。这些手段组合起来能解决 90% 以上的“卡住”问题。剩下那 10%多半是网络拓扑或企业策略导致的特殊情况需要根据实际环境再针对性调整。但至少你的 Dockerfile 不会再因为换了两行pip install就在那里干等半天了。