必须选项目虚拟环境里的Python解释器，否则Django无法启动；需通过Python: Select Interpreter选择venv路径，配置launch.json的"module": "django"和settings.json的python.django.managePyPath与settingsModule。
VSCode 选错 Python 解释器，Django 根本不会启动
90% 的 ModuleNotFoundError: No module named 'django' 都是因为 VSCode 没用你装了 Django 的那个 Python。它不继承终端激活的虚拟环境，只认你手动选中的解释器路径。
按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入并选择 Python: Select Interpreter；从列表里只选带 venv 或 env 字样的路径，例如：./venv/bin/python（Linux/macOS）或 .\venv\Scripts\python.exe（Windows）。
- 右下角状态栏必须显示该路径，不是
/usr/bin/python3或C:\Python312\python.exe - 打开任意
.py文件，悬停from django.conf import settings，确认无红线 - 仍报错？尝试在终端激活虚拟环境后启动 VSCode：
source venv/bin/activate && code .（macOS/Linux）或venv\Scripts\activate.bat && code .（Windows）
launch.json 必须用 module 启动，不能用 program 指向 manage.py
用 "program": "manage.py" 是最常见误区：VSCode 把它当普通脚本执行，跳过 Django 命令解析逻辑，runserver 参数不生效，断点进不去视图函数，环境变量也传不进去。
在项目根目录建 .vscode/launch.json，关键配置如下：
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。
{
"version": "0.2.0",
"configurations": [
{
"name": "Django",
"type": "python",
"request": "launch",
"module": "django",
"args": ["runserver", "--noreload", "8000"],
"django": true,
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
]
}
-
"module": "django"强制走python -m django启动，避免子进程 fork 导致断点丢失 -
--noreload是必须项，否则调试器只附着在父进程，请求处理线程里断点无效 -
"django": true启用模板上下文、URL 路由跳转等 Django 特有支持 -
DJANGO_SETTINGS_MODULE必须显式写全模块路径，不能依赖默认值
settings.json 里漏配 managePyPath 和 settingsModule，功能就残缺
没有这两项，VSCode 不识别 Django 项目结构：Run Server 按钮灰掉、models.py 点不进去、模板语法无提示、{% url %} 无法跳转——不是插件没装好，是根本没告诉 VSCode “这是个 Django 项目”。
在工作区根目录的 .vscode/settings.json 中加入：
{
"python.django.managePyPath": "./manage.py",
"python.django.settingsModule": "myproject.settings"
}
-
managePyPath必须是相对路径，不能写成/full/path/to/manage.py -
settingsModule是 Python 模块路径（如myproject.settings.dev），不是文件路径 - 如果
settingsModule错了，调试时INSTALLED_APPS为空，中间件、静态路由全失效
静态文件 404、环境变量读不到，问题不在代码而在加载时机
访问 /static/css/app.css 返回 404，不是 STATIC_URL 配错了，而是开发服务器根本没注册静态路由；os.getenv('DEBUG') 返回 None，不是没设环境变量，而是读得太早——Django 配置还没加载，或者 launch.json 的 env 没注入到子进程。
- 确保
DEBUG = True，并在主urls.py末尾加：from django.conf import settings; from django.conf.urls.static import static; urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT) - 环境变量优先在
launch.json的env字段硬编码，比如"DEBUG": "1"、"DATABASE_URL": "sqlite:///db.sqlite3" - 避免在模块顶层（如
__init__.py或settings.py开头）直接调用os.getenv()；改用settings.DEBUG这类延迟求值方式
真正卡住人的，往往不是哪行代码写错了，而是解释器、launch.json、settings.json 三者之间没对齐——少一个，调试就断链。
