Gunicorn 启动 Django 项目提示 ModuleNotFoundError 怎么排查？

大多数情况下，这个问题是因为 Gunicorn 使用的 Python 解释器或环境变量与你开发时不一致，导致无法找到 Django 包或项目模块。

先说结论：优先检查 Gunicorn 运行的虚拟环境是否激活，以及项目目录是否被正确添加到 Python 搜索路径中。

先确认：运行 Gunicorn 的 python 路径是否指向虚拟环境
先处理：确认虚拟环境中依赖已安装或使用绝对路径启动
再验证：查看进程环境变量及错误日志确认模块加载情况

命令速用版

如果你需要快速尝试恢复，可以先确认当前环境的 Python 路径，并使用绝对路径启动：

# 确认当前 python 路径
which python

# 确认 gunicorn 路径
which gunicorn

# 尝试指定 python 路径启动（示例）
/path/to/venv/bin/gunicorn myproject.wsgi:application

为什么会这样

Gunicorn 是一个 WSGI HTTP 服务器，它启动时会加载 Python 解释器并导入指定的模块。如果启动命令所在的 shell 环境没有激活虚拟环境，或者 systemd、supervisor 等进程管理器没有继承正确的环境变量，Python 就只能在系统库中查找模块。而 Django 项目通常安装在虚拟环境中，系统 Python 自然找不到对应的包，从而抛出 ModuleNotFoundError。

分步处理

检查虚拟环境激活状态

在终端执行 which python 和 which gunicorn。如果显示的是 /usr/bin/python 而不是虚拟环境目录（如 /home/user/project/venv/bin/python），说明环境未激活。

解决方法：激活虚拟环境后确认依赖已安装，或使用虚拟环境内的绝对路径启动。
检查项目路径

确保启动命令在项目根目录下执行，或者使用 `--chdir` 参数指定工作目录。
```
gunicorn `--chdir` /path/to/project myproject.wsgi:application
```
如果项目结构特殊，可能需要手动设置 PYTHONPATH：
```
export PYTHONPATH=/path/to/project:$PYTHONPATH
gunicorn myproject.wsgi:application
```
检查依赖安装

在确认的虚拟环境中执行以下命令确保 Django 及其他依赖已安装：
```
pip install -r requirements.txt
pip list | grep django
```
Systemd 配置示例（生产环境）

如果使用 systemd 管理 Gunicorn，需在 service 文件中显式指定环境变量和工作目录，因为它不会自动加载用户的 .bashrc。
```
[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/project
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/gunicorn `--workers` 3 myproject.wsgi:application
```

怎么验证是否生效

启动后观察终端输出，如果没有报错且看到 Listening at: http://... 字样，说明启动成功。也可以访问服务器 IP 和端口，看是否返回 Django 默认页面或你的应用内容。同时检查日志文件，确认没有 ImportError 相关的 traceback。

常见坑

Systemd 环境变量丢失：必须在 service 文件中显式指定 Environment 或 WorkingDirectory。
项目包名冲突：确保你的项目文件夹名称没有与标准库或已安装包重名，否则 Python 会优先导入本地文件夹而不是真正的包。
wsgi.py 路径错误：Gunicorn 命令末尾的模块路径必须指向正确的 wsgi 文件，通常是 project_name.wsgi:application。