VSCode配置Django框架 Python后端必备VSCode开发环境

先说一个最容易被忽略的结论：VSCode 能跑 Django，但默认配置下几乎必然失败。这从来不是代码的问题，基本可以断定是你的编辑器在解释器、路径、调试模式这三者之间没能达成共识——它们没对齐，项目就跑不起来。

Python 解释器选错，是 90% 的 ImportError 根源

有意思的是，很多开发者在终端里用 python -m django --version 明明能跑，可一回到 VSCode 就报错 No module named 'django'。原因其实很简单：VSCode 并不继承你 shell 里的环境变量，它只认你手动指定的那个解释器路径。你不知道它用的是哪个 Python，它就真的给你乱用一个。

• 快捷键 Ctrl+Shift+P（macOS 是 Cmd+Shift+P），输入 Python: Select Interpreter，这里的选择至关重要。
• 务必从列表中挑选带有 venv 或 env 字样的路径。比如 Linux/macOS 下的 ./venv/bin/python，或 Windows 下的 .\venv\Scripts\python.exe。
• 检查 VSCode 窗口右下角的状态栏，必须能看到你刚才选定的解释器路径。如果显示的是系统自带的全局 Python（如 /usr/bin/python3），那问题就出在这儿。
• 最后，随便打开项目中的一个 .py 文件，把鼠标悬停在 from django.conf import settings 这行代码上。确认没有出现任何红色波浪线，这才是真正的“检验通过”。

launch.json 里写的是 module，不是 program

很多人习惯直接去运行 manage.py，但这在 VSCode 的调试体系中是大忌。这会让 VSCode 把它当作一个普通脚本执行，直接跳过了 Django 命令的解析逻辑。后果就是：runserver 的参数不生效，你打的断点也永远进不去视图函数。

• 正确的做法是：在 .vscode/launch.json 中添加配置时，"type" 和 "request" 字段保持默认，但必须把 "program" 改为 "module": "django"。
• "args" 字段要写成 ["runserver", "--noreload"]。千万要带上 --noreload，否则 Django 会 fork 出一个子进程，而 VSCode 调试器只会附着在父进程上，你的断点就全落在了一个“局外”进程里，形同虚设。
• 一定要加上 "django": true。没有这一行，调试器就不会启用针对 Django 框架的特殊支持，比如模板渲染上下文、请求对象展开这些便捷功能都用不了。
• 别在 manage.py 文件里打断点。这行脚本只执行一次就结束了，真正处理 HTTP 请求的线程是 django.core.servers.basehttp 启动的。断点要打在视图函数里。

settings.json 必须显式声明项目结构

即便解释器和启动配置都对上了，如果你发现 VSCode 的 Run Server 按钮是灰色的，或者点击跳转不到 models.py，大概率是这一步漏掉了——VSCode 并不知道你的项目结构，你需要明确告诉它。

• 在工作区根目录下的 .vscode/settings.json 文件中，必须加入这两行配置：

  {  "python.django.managePyPath": "./manage.py",  "python.django.settingsModule": "myproject.settings"}

• managePyPath 必须使用相对路径；settingsModule 则是 Python 模块的路径（比如 myproject.settings.dev），不是文件系统路径。
• 如果 settingsModule 填错了，调试时你会发现 INSTALLED_APPS 为空，所有的静态文件路由、中间件都会失效。
• 务必确认 myproject/__init__.py 文件存在。没有这个文件，Python 就无法把这个目录识别为一个模块，导入自然会失败。

环境变量得靠 launch.json 硬塞过去

你是不是遇到过 os.getenv('DEBUG') 返回 None？原因不是你忘记读 .env 文件，而是 VSCode 的调试器压根没有把系统环境变量传递给子进程。这个坑，几乎每个人都踩过。

• 解决方案是在 launch.json 的调试配置中加上 env 字段：

  "env": {  "DJANGO_SETTINGS_MODULE": "myproject.settings",  "PYTHONUNBUFFERED": "1"}

• 不要指望 manage.py 来自动处理，这种机制只在命令行下有效。在 VSCode 调试模式下，启动路径完全不同。
• 如果你用了 django-environ，要确保 .env 文件与 manage.py 同级，并且在 settings.py 文件的顶部就已经执行了 env = environ.Env() 的初始化操作。
• 即便你在 settings.py 里写死了 DEBUG=True，它和调试器能否读取到环境变量是两回事。环境变量必须由调试器注入才真正生效，这是一个必须刻意配置的步骤。

最后必须强调一个最容易被忽略的组合：--noreload 和 "django": true，这两项缺一不可。前者确保了你的断点能落在真实的请求处理线程里，而不是僵尸进程上；后者则让 VSCode 知道“这是一个 Django 项目，别把它当普通脚本跑”。这两项遗漏任何一项，调试体验就瞬间倒退回“改代码 + 加 print()”的原始时代。这才是问题的关键所在。