Docker部署Python/Django应用报错：缺失_distutils_hack及django模块

核心问题分析 #

这两个错误本质是Python运行环境无法定位正确的依赖包，大概率是镜像构建时依赖安装不完整，或是Apache配置指定的Python解释器路径未指向安装了依赖的环境。

针对性修复步骤 #

1. 修正Dockerfile中的依赖安装逻辑 #

确保依赖完整安装到Apache使用的Python环境中：

• 避免使用pip install --user，Apache运行用户可能无法访问用户目录下的包
• 明确指定Python版本，防止镜像默认版本变更引发环境不一致
• 添加--no-cache-dir避免缓存导致的依赖缺失

示例修正后的Dockerfile片段：

# 选用带Apache和mod_wsgi的Python官方镜像
FROM python:3.11-apache

# 设置项目工作目录
WORKDIR /var/www/html

# 先复制依赖清单并安装，利用构建缓存优化
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 配置Apache站点
COPY demo_site.conf /etc/apache2/sites-available/
RUN a2ensite demo_site.conf && a2dissite 000-default.conf

# 启动Apache服务
CMD ["apache2-foreground"]

2. 调整Apache配置（demo_site.conf）的Python路径 #

确保WSGI脚本使用的Python解释器与安装依赖的环境一致：

• 通过WSGIPythonHome或WSGIPythonPath指定正确的Python环境路径
• 若使用虚拟环境，需在配置中明确指向虚拟环境的Python目录

示例修正后的配置片段：

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html

    WSGIDaemonProcess demo_site python-path=/var/www/html python-home=/usr/local/lib/python3.11/site-packages
    WSGIProcessGroup demo_site
    WSGIScriptAlias / /var/www/html/demo_site/wsgi.py

    <Directory /var/www/html/demo_site>
        <Files wsgi.py>
            Require all granted
        </Files>
    </Directory>

    Alias /static/ /var/www/html/static/
    <Directory /var/www/html/static>
        Require all granted
    </Directory>
</VirtualHost>

3. 清理Docker缓存并重新构建 #

旧镜像缓存可能保留错误环境，执行以下命令彻底重建：

# 停止并删除现有容器
docker-compose down

# 删除旧镜像与缓存
docker-compose rm -f
docker system prune -f

# 无缓存构建并启动服务
docker-compose build --no-cache
docker-compose up -d

4. 验证依赖安装状态 #

进入运行中的容器，确认依赖是否正确安装：

# 替换为实际容器名称
docker exec -it your-container-name bash

# 检查Django是否安装
pip list | grep Django

# 检查_distutils_hack（属于setuptools组件）
pip list | grep setuptools
# 若缺失则手动安装：pip install --upgrade setuptools

额外注意事项 #

• 确保requirements.txt明确指定Django版本，例如Django==4.2.5
• 若使用虚拟环境，Dockerfile需创建并激活虚拟环境，且Apache配置要指向虚拟环境的Python路径
• 调整项目文件权限，确保Apache用户（通常为www-data）有读取权限：

  RUN chown -R www-data:www-data /var/www/html
  

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