Heroku部署失败但构建成功：Django模块找不到问题排查

数据老陈

2026-7-23

问题描述

在Heroku部署时构建流程通过，但运行阶段出现ModuleNotFoundError: No module named 'django'错误，具体报错信息如下：

Traceback (most recent call last):
  File "/app/manage.py", line 11, in main
    from django.core.management import execute_from_command_line
ModuleNotFoundError: No module named 'django'
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/app/manage.py", line 22, in <module>
    main()
  File "/app/manage.py", line 13, in main
    raise ImportError(
ImportError: Couldn't import Django. Are you sure it's installed and available on your PYTHONPATH environment variable? Did you forget to activate a virtual environment?

已确认requirements.txt包含Django依赖，完整内容如下：

asgiref==3.6.0
cachetools==5.3.0
certifi==2022.12.7
chardet==3.0.4
charset-normalizer==2.1.1
dj-database-url==1.2.0
Django==3.2
django-bunny-storage==0.1.2
django-countries==7.5.1
django-extensions==3.2.1
django-phone-auth==0.3.1
django-phonenumber-field==7.0.2
django-storages==1.13.2
djangorestframework==3.14.0
djangorestframework-jwt==1.11.0
djangorestframework-simplejwt==5.2.2
google-api-core==2.11.0
google-auth==2.17.3
google-cloud-core==2.3.2
google-cloud-storage==2.8.0
google-crc32c==1.5.0
google-resumable-media==2.5.0
googleapis-common-protos==1.59.0
gunicorn==20.1.0
idna==2.10
isort==5.12.0
phonenumbers==8.13.5
Pillow==9.4.0
protobuf==4.22.3
psycopg2-binary==2.9.5
pyasn1==0.5.0
pyasn1-modules==0.3.0
pycountry==22.3.5
PyJWT==1.7.1
python-dateutil==2.8.2
python-dotenv==0.15.0
pytz==2022.7.1
requests==2.28.1
rsa==4.9
six==1.16.0
sqlparse==0.4.3
twilio==6.63.2
typing_extensions==4.4.0
urllib3==1.26.12
uuid==1.30
whitenoise==6.4.0

Procfile配置：

web: gunicorn pixsar.wsgi --log-file -
release: python manage.py migrate

.gitlab.yml配置：

image:
  name: docker/compose:1.25.4
  entrypoint: [""]

services:
  - docker:dind

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_DRIVER: overlay2

stages:
  - deploy-stag

deploy-stag:
  stage: deploy-stag
  image: ruby:latest
  before_script:
    - gem install dpl
    - wget -qO- https://cli-assets.heroku.com/install-ubuntu.sh | sh
  script:
    - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY
    - export HEROKU_API_KEY=$HEROKU_API_KEY
    - heroku run --app $HEROKU_APP_NAME python manage.py migrate
    - heroku run --app $HEROKU_APP_NAME python manage.py collectstatic --noinput
  only:
    - develop

可能的问题及解决方法

确认requirements.txt路径与可见性：
确保requirements.txt在项目根目录，且未被.gitignore排除——如果文件不在根目录，需要在dpl命令中指定路径：dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY --requirements=path/to/requirements.txt；如果被.gitignore排除，依赖文件不会被推送到Heroku，直接导致依赖缺失。
检查Heroku构建日志中的依赖安装步骤：
登录Heroku控制台查看应用的Build日志，确认是否存在Installing requirements with pip的步骤，以及Django是否被成功安装。如果日志显示依赖安装失败，需排查包版本冲突或网络问题。
修正Procfile中的Python版本指向：
Heroku默认使用虚拟环境中的Python，可尝试将Procfile中的python改为python3，避免指向系统默认版本：
```
web: gunicorn pixsar.wsgi --log-file -
release: python3 manage.py migrate
```
调整CI脚本的部署逻辑：
当前CI在dpl部署后手动执行migrate和collectstatic，但如果依赖未正确安装，这些命令会直接失败。建议依赖Procfile中已配置的release阶段自动执行迁移，移除CI脚本中手动运行的heroku run命令，确保依赖安装完成后再执行数据库操作。
验证dpl部署是否触发依赖安装：
dpl默认会执行pip install -r requirements.txt，但如果部署逻辑被自定义修改，可能跳过该步骤。可在GitLab CI日志中查找依赖安装记录，若缺失，可在CI的script阶段手动添加pip install -r requirements.txt（仅针对容器部署场景，标准Heroku部署无需此操作）。

内容的提问来源于stack exchange，提问作者Lutaaya Huzaifah Idris