如何使用VSCode配置并运行Django项目进行Python后端开发？

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

VSCode 无法直接运行 Django 的原因分析：

Python 解释器选错是 90% 启动失败的根源

VSCode 不会自动继承你终端里激活的虚拟环境。它只认你在 “Python: Select Interpreter” 里手动选中的那个 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——Django 很可能没装在那里
• 选完后看 VSCode 窗口右下角是否显示该路径；再新开一个终端，执行 which python（macOS/Linux）或 where python（Windows），输出应与右下角一致

launch.json 必须配 "module": "django" 而不是 manage.py

用 program 指向 manage.py 是常见误区：它会让调试器附着在脚本启动阶段，而 Django 实际请求处理发生在子进程中，断点自然失效。

• 在项目根目录建 .vscode/launch.json，配置如下：

{ "version": "0.2.0", "configurations": [ { "name": "Django", "type": "python", "request": "launch", "module": "django", "args": ["runserver", "--noreload"], "django": true, "env": { "DJANGO_SETTINGS_MODULE": "myproject.settings" } } ] }

• "module": "django" 表示用 python -m django 启动，避免 fork 子进程导致断点丢失
• --noreload 关闭 autoreload，否则调试器无法稳定附着
• "django": true 启用 VSCode Python 扩展对 Django 模板、URL 路由等的调试支持
• DJANGO_SETTINGS_MODULE 必须显式设为你的 settings 模块路径，不能依赖默认值

环境变量（如 DEBUG、DATABASE_URL）读不到？不是没传，是读太早

os.getenv('DEBUG') 在模块顶层执行时返回 None，往往是因为 Django 配置尚未加载，或者 .env 文件没被 django-environ 读取——但更常见的是 VSCode 调试器根本没把 env 字段注入到子进程。

立即学习“Python免费学习笔记（深入）”；

• 在 launch.json 的 "env" 字段里硬编码所需变量，例如："DEBUG": "1"、"DATABASE_URL": "sqlite:///db.sqlite3"
• 如果用 django-environ，确保 .env 和 manage.py 同级，且 settings.py 顶部有 environ.Env() 初始化
• 避免在模块顶层调用 os.getenv()；改用 settings.DEBUG 这类延迟求值方式，它会在 Django 配置加载完成后才解析

静态文件 404、路由 404 不是代码写错了，是开发服务器没配对

VSCode 调试启动的 runserver 和你在终端里敲的命令行为完全一致——所以如果终端能访问 /static/css/app.css，而 VSCode 里 404，问题一定出在 URL 路由注册或 DEBUG 开关上。

• 检查主 urls.py 是否包含以下开发专用段（仅 DEBUG=True 时生效）：

from django.conf import settings from django.conf.urls.static import static urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT) if settings.DEBUG: urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

• STATIC_URL 和 STATICFILES_DIRS 配置正确 ≠ 开发服务器会自动服务静态文件——必须靠 static() 函数显式注册 URL
• 确保 settings.DEBUG = True，否则 static() 返回空列表，路由根本不注册
• 不要依赖浏览器缓存：强制刷新（Ctrl+Shift+R）或检查 Network 面板确认请求是否真的发到了 /static/ 路径

最常被忽略的一点：--noreload 不只是让断点有效，它还决定了环境变量能否稳定传递到处理请求的进程——autoreload 会反复 fork 新子进程，而 VSCode 的 env 字段只作用于初始进程。一旦漏掉这个参数，哪怕 launch.json 写得再全，os.getenv 也可能在视图里突然变 None。