如何在 VSCode 中配置并运行 Django 后端项目-VSCode-PHP中文网

必须选项目虚拟环境里的python解释器，否则django无法启动；需通过python: select interpreter选择venv路径，配置launch.json的"module": "django"和settings.json的python.django.managepypath与settingsmodule。

如何在 vscode 中配置并运行 django 后端项目

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

提供使用 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 这类延迟求值方式