本文详细指导如何在heroku平台上正确配置django应用的gunicorn procfile，解决常见的应用启动失败问题。重点阐述了gunicorn模块路径（`project_name.wsgi`）的正确写法，并强调了避免绑定本地ip及启用标准输出日志的重要性，确保django应用在heroku上稳定运行。
在Heroku上部署Django应用程序时，Procfile 文件是定义应用进程类型及其启动命令的关键。其中，Web进程通常使用Gunicorn作为WSGI HTTP服务器来运行Django应用。然而，不正确的Gunicorn配置是导致应用启动失败的常见原因。本教程将深入探讨如何正确配置Gunicorn Procfile，并分析常见的错误及其解决方案。
理解Heroku Procfile与Gunicorn
Procfile 是一个简单的文本文件，位于应用程序的根目录，用于声明应用程序的进程类型（如 web、worker 等）以及每个进程类型的启动命令。对于Web应用，web 进程是必需的，它负责接收HTTP请求。
Gunicorn（Green Unicorn）是一个Python WSGI HTTP服务器，它通常用于在生产环境中运行Django等WSGI应用程序。在Heroku上，Gunicorn负责接收来自Heroku路由器（router）的请求，并将其转发给Django应用处理。
常见的Procfile配置错误分析
许多部署失败的情况都源于Procfile中Gunicorn命令的误配置。以下是两种常见的错误及其原因：
错误示例一：指定本地IP和不正确的模块路径
web: gunicorn SC_BASIS:application -b 127.0.0.1:8000
问题分析：
- SC_BASIS:application: Gunicorn尝试在 SC_BASIS 模块中查找名为 application 的属性。在标准的Django项目中，WSGI应用对象通常位于 project_name.wsgi 模块中，并被命名为 application。这里的 SC_BASIS 可能是一个Django应用（app）的名称，而不是包含 wsgi.py 文件的项目（project）根目录名称。Gunicorn需要的是指向WSGI入口点的正确模块路径，即 project_name.wsgi。如果 SC_BASIS 不是项目根目录，或者 wsgi.py 文件不在此路径下，Gunicorn将无法找到 application 对象。
- -b 127.0.0.1:8000: 这个参数指示Gunicorn绑定到本地回环地址 127.0.0.1 的 8000 端口。在Heroku环境中，应用程序不应该手动指定绑定地址和端口。Heroku会通过环境变量 PORT 动态分配一个端口，并期望应用程序绑定到 0.0.0.0:$PORT。绑定到 127.0.0.1 会导致Heroku路由器无法访问你的应用，从而引发 H10 App crashed 错误。
错误日志示例：
Failed to find attribute 'application' in 'SC_BASIS'. ... gunicorn.errors.HaltServer: <HaltServer 'App failed to load.' 4> ... heroku[router]: at=error code=H10 desc="App crashed" method=GET path="/" ... status=503
日志清晰地指出Gunicorn无法在指定模块中找到 application 属性，以及应用最终崩溃。
错误示例二：缺少日志配置
web: gunicorn SCBASIS.wsgi
问题分析：
- SCBASIS.wsgi: 假设 SCBASIS 是你的Django项目根目录的名称，那么 SCBASIS.wsgi 是一个正确的WSGI模块路径。Gunicorn会在此模块中找到 application 对象。
- 缺少 --log-file -: 虽然这个命令可能能够启动Gunicorn，但它没有明确指示Gunicorn将日志输出到标准输出（stdout）。在Heroku上，应用程序的日志必须输出到stdout或stderr才能被Heroku的日志系统捕获。如果缺少此配置，你将无法在Heroku日志中看到Gunicorn的详细运行信息，给调试带来困难。
正确的Gunicorn Procfile配置
基于上述分析，一个健壮且符合Heroku最佳实践的Gunicorn Procfile配置应如下所示：
web: gunicorn project_name.wsgi --log-file -
各部分详解：
- web:: 声明这是一个Web进程，Heroku将为此进程分配HTTP流量。
- gunicorn: 启动Gunicorn服务器。
-
project_name.wsgi: 这是最关键的部分。
- project_name：指代你的Django项目的根目录名称。这个目录通常包含 settings.py 和 wsgi.py 文件。
- .wsgi：表示Gunicorn将加载 project_name 目录下的 wsgi.py 文件，并使用其中定义的 application 对象作为WSGI入口。
- 如何确定 project_name？ 找到你项目中包含 settings.py 和 wsgi.py 文件的那个目录，它的名称就是 project_name。例如，如果你的项目结构是 myproject/myproject/settings.py，那么 project_name 就是外层的 myproject。
- --log-file -: 这个参数告诉Gunicorn将所有日志输出到标准输出（stdout）。Heroku的日志聚合系统会捕获这些输出，并将其显示在 heroku logs --tail 命令中，极大地便利了应用的监控和调试。
部署前检查清单（注意事项）
除了正确的Procfile配置外，确保Django应用在Heroku上成功部署还需要关注以下几个方面：
-
requirements.txt:
- 确保包含 gunicorn。
- 如果使用PostgreSQL数据库，需包含 psycopg2-binary。
- 为了正确处理静态文件，通常需要 whitenoise。
- 当然，Django 本身也必不可少。
- 示例：
Django>=3.0 gunicorn psycopg2-binary whitenoise
-
runtime.txt:
-
settings.py 配置:
- ALLOWED_HOSTS: 必须包含 Heroku 应用的域名。在开发阶段，可以设置为 ['.herokuapp.com', '127.0.0.1'] 或 ['*'] (生产环境不推荐 *)。
-
静态文件配置:
import os STATIC_URL = '/static/' STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles') # Whitenoise配置 STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
- WSGI_APPLICATION: 确保指向正确的WSGI模块，例如 project_name.wsgi.application。
-
数据库配置: 使用 dj_database_url 库从环境变量中读取数据库URL。
import dj_database_url DATABASES = { 'default': dj_database_url.config(conn_max_age=600, ssl_require=True) }
-
wsgi.py 文件:
-
确保文件存在于 project_name 目录下，且内容类似于：
import os from django.core.wsgi import get_wsgi_application os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project_name.settings') application = get_wsgi_application()注意 project_name.settings 需与你的项目名称一致。
-
总结
正确配置Gunicorn Procfile是Django应用在Heroku上成功部署的关键一步。核心在于确保Gunicorn能够找到正确的WSGI应用入口 (project_name.wsgi)，并且不手动绑定本地IP地址，而是让Heroku动态分配端口。同时，将Gunicorn日志输出到标准输出对于调试和监控至关重要。结合上述部署前检查清单，可以显著提高Django应用在Heroku上的部署成功率和稳定性。
