Django项目VSCode调试需满足三前提：终端位于manage.py所在目录、settings.py在Python路径中（推荐--settings显式指定）、虚拟环境已激活且VSCode选中对应解释器；launch.json关键配置为"module": "django"、"args": ["runserver", "--noreload"]、"env": {"PYTHONPATH": "${workspaceFolder}"}。
确认 Django 项目结构是否满足调试前提
VSCode 调试 Django 的核心前提是：它得能正常启动 manage.py，且你清楚当前项目根目录和 settings.py 的位置。很多“断点不命中”或“ModuleNotFoundError”其实卡在这一步。
常见错误现象：ModuleNotFoundError: No module named 'myapp'、django.core.exceptions.ImproperlyConfigured: Requested setting DEBUG, but settings are not configured
- 确保终端 pwd 进入的是包含
manage.py的目录（不是外层 workspace，也不是venv目录） -
settings.py必须在 Python path 上——推荐用--settings=myproject.settings显式指定，而不是依赖DJANGO_SETTINGS_MODULE环境变量（容易漏设） - 虚拟环境必须已激活，且 VSCode 的 Python 解释器选中的是该 venv 下的
python（看左下角状态栏，不是靠venv文件夹名判断）
launch.json 中最关键的三个配置项
VSCode 不靠插件自动猜 Django 启动方式，launch.json 里这三项写错，断点直接失效。
使用场景：你在 views.py 打了断点，F5 启动后请求发过去，断点没亮，控制台也没报错——大概率是这里配错了。
-
"module": "django"—— 必须写，不能写"program": "./manage.py"；否则 VSCode 当普通脚本跑，不走 Django 的命令解析逻辑 -
"args": ["runserver", "--noreload"]——--noreload是关键，Django 的 auto-reloader 会 fork 子进程，VSCode 调试器无法跟踪子进程里的断点 -
"env": {"PYTHONPATH": "${workspaceFolder}"}—— 补足路径，尤其当manage.py和settings.py不在同一级时，避免 import 失败
一个最小可用示例：
{
"version": "0.2.0",
"configurations": [
{
"name": "Django Debug",
"type": "python",
"request": "launch",
"module": "django",
"args": ["runserver", "--noreload", "8000"],
"env": {
"PYTHONPATH": "${workspaceFolder}",
"DJANGO_SETTINGS_MODULE": "myproject.settings"
},
"justMyCode": true
}
]
}
为什么断点有时“看起来没生效”
不是配置失败，而是断点位置本身不在执行路径上，或者被优化跳过了。
常见错误现象：断点是灰色的、悬停显示 “Breakpoint ignored because generated code not found”，或者请求发出去但断点完全不触发。
- Django 模板渲染、静态文件服务、中间件的
process_request以外逻辑，通常不会进你写的views.py—— 先 curl 或浏览器直连 URL，确认请求真走到那个 view - 用了类视图（
APIView、TemplateView）？断点要打在get()/post()方法内，别打在类定义或as_view()调用处 -
justMyCode: true是默认值，它会跳过所有 site-packages 里的代码（包括 Django 自身），这是对的；但如果误设为false，你会在 Django 内部堆栈里疯狂跳转，反而找不到自己的逻辑
调试异步视图或 Celery 任务怎么办
VSCode 默认的 django module 启动方式只支持同步 WSGI 请求。想调 async def my_view 或 Celery @task，得换路子。
性能 / 兼容性影响：强行用 runserver 调 async view 会报 RuntimeError: Cannot run the event loop while another loop is running；Celery 则根本不会进调试器。
- 异步视图：改用
"program": "${workspaceFolder}/manage.py"+"args": ["runserver", "--nothreading", "--noreload"]，并确保 Python 解释器 >= 3.11，Django >= 4.1 - Celery 任务：单独建一个配置，
"module": "celery"，"args": ["-A", "myproject.celery", "worker", "--loglevel=info"]，再配合breakpoint()或日志断点 - 更稳的做法：把待调试逻辑抽成普通函数，在
manage.py shell里手动调用，直接 F9 打断点
复杂点在于：Django 的异步支持和 Celery 的 worker 模型，跟 VSCode 的单进程调试模型天然有隔阂。别指望一个 launch 配置通吃所有场景。
