如何设置VSCode以支持Django框架的开发配置？

本文共计968个文字，预计阅读时间需要4分钟。

VSCode 调试 Django 应用，无需图形化界面，不涉及数数，不超过100字，直接输出结果：

Python 解释器必须选对虚拟环境里的 python

VSCode 不会自动继承你在终端里激活的虚拟环境。它只看当前工作区指定的可执行文件路径，哪怕你终端里 python -m django --version 能跑，VSCode 仍可能报 ModuleNotFoundError: No module named 'django'。

• 按 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:\Python39\python.exe 这类系统级路径——Django 包不在那儿
• 选完后，右下角状态栏必须显示该路径；再打开一个 .py 文件，悬停 from django.conf import settings 应无红线

launch.json 必须用 module: "django"，不能用 program 指向 manage.py

把 manage.py 当普通脚本跑，VSCode 就绕过了 Django 的命令解析逻辑，runserver 参数不生效，环境变量也不传，断点更不会命中。

• 在项目根目录建 .vscode/launch.json，用 Python: Django 模板生成基础配置
• "module" 字段必须是 "django"，不是 "manage"，也不能留空
• "args" 至少包含 ["runserver", "--noreload"]：缺 --noreload 会导致 Django fork 子进程，VSCode 只调试主进程，断点全失效
• "env" 中补上 "DJANGO_SETTINGS_MODULE": "myproject.settings"（替换成你实际的模块路径）和 "PYTHONPATH": "${workspaceFolder}"

settings.json 要显式声明 manage.py 和 settings 模块位置

光有解释器和 launch.json 还不够。VSCode 的 Python 插件需要知道项目结构，否则调试按钮会灰掉、跳转不到 models.py、甚至 Run Server 功能不可用。

• 在项目根目录下 .vscode/settings.json 中加这三行：
• "python.django.managePyPath": "./manage.py"（必须是相对路径，不能是绝对路径）
• "python.django.settingsModule": "myproject.settings"（这是 Python 模块名，不是文件路径；对应 myproject/__init__.py 所在包）
• 如果用了多配置，比如 settings/dev.py，这里填 "myproject.settings.dev"，但得确保能被 import

静态文件 404？先检查 urls.py 是否注册了 static()

开发时访问 /static/css/app.css 返回 404，不是 STATIC_URL 配错了，而是 Django 开发服务器根本没接管静态请求——它默认不代管，除非你手动注册。

• 在主 urls.py（通常是 myproject/urls.py）末尾加：
• from django.conf import settings
• from django.conf.urls.static import static
• urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
• 注意：这段只在 DEBUG=True 时生效，上线必须用 Nginx 等代理处理静态文件

最容易被忽略的是 --noreload 和 DJANGO_SETTINGS_MODULE 的组合：漏掉任一，断点就形同虚设；而 settingsModule 值写成文件路径（如 "myproject/settings.py"）而不是模块路径，会让整个调试配置静默失效——VSCode 不报错，但所有功能都卡住。