VSCode调试Django报ModuleNotFoundError，主因是未正确选择虚拟环境解释器；需通过Python: Select Interpreter选venv路径，并在launch.json中配置"module": "django"、"--noreload"及DJANGO_SETTINGS_MODULE。

ModuleNotFoundError: No module named 'django' 这类报错，八成不是没装 Django，而是 VSCode 根本没用对 Python 解释器。它不看你在终端里 pip install 了什么，只认当前工作区指定的那个 python 可执行文件路径。

---

选对解释器是第一道生死线

VSCode 启动调试、代码补全、跳转、甚至 import 提示，全依赖它知道“哪个 python”在跑你的项目。选错，后面全白搭。

• 常见错误现象：from django.conf import settings 报红线、manage.py 右键 Run Python File 失败、终端里 python -m django --version 能跑，但 VSCode 里就是找不到模块
• 实操建议：
  • 按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Python: Select Interpreter
  • 从列表中只选带 venv 或 env 字样的路径，例如：./venv/bin/python（macOS/Linux）或 .\venv\Scripts\python.exe（Windows）
  • 绝对别选 /usr/bin/python3、C:\Python39\python.exe 这类系统级路径
  • 选完后，看窗口右下角状态栏是否显示你预期的路径；再打开一个 .py 文件，悬停 import django 看有没有红线

---

launch.json 里 module 必须是 django，不是 manage.py

点绿色三角直接跑 manage.py，VSCode 会把它当普通脚本执行，跳过 Django 的命令注册逻辑——结果就是 runserver 不启动、断点不命中、环境变量不生效。

Django

避免常见的 Django 错误——QuerySet 评估、N+1 查询、迁移冲突和 ORM 陷阱。

下载

• 使用场景：你在 views.py 打了断点，F5 启动后请求发过去，控制台输出了 Starting development server，但断点完全没亮
• 关键配置项：
  • "module": "django" —— 强制走 python -m django 启动流程
  • "args": ["runserver", "--noreload"] —— --noreload 是必须的，Django 自动重载会 fork 子进程，VSCode 调试器只附着在主进程上
  • "env" 字段里至少写上："DJANGO_SETTINGS_MODULE": "myproject.settings"（替换成你实际的模块路径）
• 一个最小可用片段：

  {
  "name": "Django Debug",
  "type": "python",
  "request": "launch",
  "module": "django",
  "args": ["runserver", "--noreload", "8000"],
  "env": {
    "DJANGO_SETTINGS_MODULE": "myproject.settings",
    "PYTHONPATH": "${workspaceFolder}"
  }
  }
  

---

模板不高亮、{% url %} 点不进去？不是插件没装，是文件关联和引用方式错了

VSCode 默认把 .html 当纯 HTML 解析，根本不知道 {{ }} 和 {% %} 是啥。跳转失败也常因 urls.py 写法太“灵活”。

• 常见错误现象：右下角语言模式显示 HTML，{% if user %} 全白、{% url 'detail' %} 右键 Go to Definition 无效
• 实操建议：
  • 点击右下角语言标识 → Configure File Association for '.html' → 输入 django-html（注意拼写，不是 Django 或 HTML (Django Templates)）
  • 确保已安装官方扩展 Django（ID：batisteo.vscode-django）
  • urls.py 中必须用函数引用，不能用字符串：path('user/', views.user_list) ✅，path('user/', 'myapp.views.user_list') ❌
  • 视图函数必须定义在 views.py 顶层，不能包在 if DEBUG: 或闭包里
  • 如果用了命名空间，{% url 'blog:post_detail' %} 必须完整拼写，少一个冒号就失效

---

--noreload 不只是防崩溃，它决定了你能看见什么变量

开了自动重载，Django 主进程只负责监听文件变化并重启子进程；真正处理 HTTP 请求的是子进程里的线程。VSCode 调试器默认只 attach 主进程，所以你看到的 request 对象永远是空的、用户永远未认证、POST 数据永远读不到。

• 容易被忽略的地方：
  • 即使你加了 "--noreload"，如果 launch.json 里同时写了 "program": "./manage.py"，VSCode 仍可能绕过 module: django 的逻辑，导致重载未真正禁用
  • 断点必须打在 views.py、models.py、serializers.py 这类业务文件里，manage.py 本身只运行一次，打那里没意义
  • 如果用 Celery 或自定义命令调试，"program" 可以保留，但 "args" 得换成对应命令名，且去掉 --noreload（它不支持）

你配完能进断点、能看到 request.GET 和 request.user，才算是真正把调试链路打通了。