本地正常运行的Django应用部署到Heroku出现H10错误求解决

问题背景 #

• 本地运行正常，部署Heroku后触发H10错误导致应用崩溃
• 最初使用SQLite数据库，尝试PythonAnywhere部署失败后转至Heroku
• 核心错误日志：ModuleNotFoundError: No module named 'recipe_app'

项目目录结构 #

RECIPE-APP/
 |-include/
 |-Lib/
 |-Scripts/
 |-src/
  |-media/recipes/
  |-recipe_app/
   |-settings.py
   |-wsgi.py
  |-recipes/
 |-.env
 |-data.json
 |-db.sqlite3
 |-manage.py
|-.gitatributes
|-.gitignore
|-Procfile
|-pyvenv.cfg
|-requirements.txt

当前配置情况 #

Procfile配置 #

web: gunicorn src.recipe_app.wsgi --log-file -

本地数据库配置（settings.py） #

DATABASES = {
        'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME' : config('DB_NAME'),
        'USER' : config('DB_USER'),
        'PASSWORD' : config('DB_PASSWORD'), 
        'HOST' : config('DB_HOST'),
        'PORT' : config('DB_PORT')
}
}

• Heroku端已同步.env中的数据库密钥到配置变量
• 针对Heroku的配置包含dj_database_url相关代码

解决思路 #

从ModuleNotFoundError核心错误入手，按以下步骤排查：

1. 补全Python包标识文件

   • 检查src、src/recipe_app、src/recipes目录下是否存在__init__.py空文件，没有则创建，让Python识别这些目录为可导入的包。

2. 调整Gunicorn启动路径

   • 尝试修改Procfile，显式指定Python路径：

     web: PYTHONPATH=./src gunicorn recipe_app.wsgi --log-file -
     

   • 或在src/recipe_app/wsgi.py开头添加路径配置：

     import sys
     import os
     sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
     

3. 检查Git提交完整性

   • 确认.gitignore未排除src/recipe_app下的__init__.py、wsgi.py等核心文件，执行git status查看是否有未提交的必要文件，确保所有关键代码已推送到Heroku。

4. 验证Heroku环境目录结构

   • 登录Heroku控制台执行heroku run bash，进入应用目录后查看src及子目录的文件是否齐全；执行python -c "import recipe_app"测试模块导入，定位具体失败原因。

5. 确认依赖完整性

   • 确保gunicorn、dj-database-url、psycopg2-binary（或psycopg2）已添加到requirements.txt，本地执行pip freeze > requirements.txt同步所有依赖后重新部署。

6. 修正Heroku数据库配置

   • 确保Heroku环境下数据库配置正确加载，示例配置：

     import dj_database_url
     if os.environ.get('HEROKU'):
         DATABASES['default'] = dj_database_url.config(conn_max_age=600, ssl_require=True)
     

   • 安装django-heroku包后，在settings.py末尾添加：

     import django_heroku
     django_heroku.settings(locals())
     

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