Django 启动遇到 ModuleNotFoundError 核心原因通常是 Python 解释器路径不一致或依赖包缺失。排查时优先确认虚拟环境激活状态，再检查代码导入路径配置。

真实报错日志分析

典型报错如下，注意 traceback 最后一行指出的缺失模块名：

Traceback (most recent call last):
  File "manage.py", line 22, in <module>
    main()
  File "manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  ...
ModuleNotFoundError: No module named 'rest_framework'

如果是 rest_framework 等第三方包，说明依赖未安装；如果是项目内部的 apps.user，则说明路径配置有问题。

核心排查步骤

1. 检查虚拟环境与解释器

在终端执行 which python（Linux/macOS）或 where python（Windows）。确认输出路径包含虚拟环境目录（如 .venv/bin/python），而非系统全局路径（如 /usr/bin/python）。

若路径不对，激活虚拟环境：

source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate    # Windows

2. 区分缺失模块类型

查看报错中的模块名。若是第三方包（如 requests），执行 pip install 包名；若是本地应用（如 apps.blog），不要使用 pip 安装，应检查项目结构及路径配置。

3. 检查 settings.py 配置

打开 settings.py，核对 INSTALLED_APPS 列表。确保注册的应用名称与文件夹结构一致，且文件夹下存在 __init__.py 文件。

4. 配置 PYTHONPATH 环境变量

若本地模块仍无法导入，可能是 Python 搜索路径缺失。在项目根目录执行：

export PYTHONPATH=$(pwd):$PYTHONPATH  # Linux/macOS
set PYTHONPATH=%cd%;%PYTHONPATH%       # Windows

5. IDE 解释器配置检查

• PyCharm：进入 Settings > Project > Python Interpreter，确认选中项目虚拟环境。
• VSCode：点击右下角 Python 版本，选择包含项目依赖的解释器。

生产环境部署专项

本地正常但服务器报错，通常是因为启动命令未指定工作目录或路径。

Gunicorn 启动：确保使用 `--chdir` 指定项目根目录，或使用绝对路径导入。

gunicorn `--chdir` /path/to/project myproject.wsgi:application

uWSGI 配置：在 .ini 文件中添加 pythonpath 参数。

[uwsgi]
pythonpath = /path/to/project

验证与常见坑

验证方法：

执行 python manage.py check。若无报错且返回 System check identified no issues，说明模块导入问题解决。随后尝试 python manage.py runserver 观察控制台。

常见坑：

• 大小写敏感：Linux 下模块名大小写必须完全匹配，Windows 可能忽略这一点导致本地正常线上报错。
• 循环导入：报错显示找不到模块，实际是文件互相 import 导致初始化失败，检查 models.py 和 views.py 之间的引用。
• requirements.txt 未更新：部署前确保执行 pip freeze > requirements.txt 同步最新依赖。