Django Cookiecutter Docker构建失败：执行build时卡顿报错

执行docker-compose -f local.yml build部署cookiecutter-django本地环境时，进程卡在pip wheel步骤并报错，已执行docker system prune -a清理所有镜像后重新构建，问题仍未解决，且已确认系统依赖齐全。

排查与修复建议 #

1. 解决PyPI网络访问问题 #

pip wheel阶段卡顿/报错大多是拉取包超时导致，直接在Dockerfile中替换为国内PyPI镜像：

• 修改Dockerfile中的pip安装步骤，添加镜像源参数：

  RUN pip install --no-cache-dir --upgrade pip \
      && pip install --no-cache-dir --index-url https://pypi.tuna.tsinghua.edu.cn/simple -r /requirements/local.txt
  

• 或者全局配置pip镜像：

  RUN mkdir -p /root/.pip && echo -e "[global]\nindex-url = https://pypi.tuna.tsinghua.edu.cn/simple" > /root/.pip/pip.conf
  

2. 排查requirements依赖冲突 #

• 打开requirements/local.txt，检查是否存在版本冲突的包（比如A包要求B>=2.0，C包要求B<1.5），这类冲突会导致pip在解析依赖时无限循环卡顿。
• 尝试注释掉非核心依赖，分阶段构建，定位到具体出问题的包后调整版本。

3. 提升Docker资源分配 #

Docker默认资源配额不足时，pip编译wheel会因CPU/内存不够卡顿：

• 打开Docker Desktop设置，将CPU核心数调至2核以上，内存调至4GB以上，重启Docker后重新构建。

4. 优化pip wheel构建命令 #

如果Dockerfile中存在自定义的pip wheel步骤，添加--no-cache-dir参数减少IO负载：

RUN pip wheel --no-cache-dir -r /requirements/local.txt -w /wheels

5. 手动定位问题包 #

如果构建进程未退出，通过docker ps找到当前运行的容器ID，执行docker exec -it <容器ID> /bin/bash进入容器，手动执行pip wheel <包名>逐个测试，找到导致卡顿的包后单独处理（比如换版本、预编译wheel）。

需补充的信息 #

• pip wheel阶段的具体报错日志
• local.yml和Dockerfile的完整配置代码

内容的提问来源于stack exchange，提问作者PapaSmurf