VSCode如何调试Python代码_断点调试详细图文教程

写过Python的老手应该都遇到过这种诡异场面：明明在VS Code里打了红点，程序却像个没事人一样跑完全程。那一刻的困惑，不亚于看悬疑片到精彩处突然黑屏。其实原因并不玄乎——90%的“断点不生效”事件，都指向同一个黑手：debugpy根本没加载到目标代码。而症结就藏在launch.json配置、解释器路径，以及你按下的到底是F5还是小三角。

先说个直观的：VS Code上的红点只代表你“想”在哪停下，不等于调试器就一定搭理你。经常是F5一按，控制台刷刷几行日志就结束了，光标根本没停在预期的那一行。这时候别急着怀疑人生，先排查四个最基础的硬伤。

比如，你兴冲冲在utils.py里打了断点，可主入口是app.py，而且根本没import utils——那这个断点就等于架设在了不存在的建筑上，完全无效。再比如，编译器端那个绿色小三角（Run Code）和调试图标栏里的▶️（Start Debugging）是两码事：前者只是终端直接执行，后者才会走launch.json的配置。如果你点错了，程序当然不会听断点的话。

还有一些更隐蔽的坑。比如文件路径带中文或空格，在Windows下debugpy会默默罢工，既不报错也不说明，十分狡猾。建议养成习惯，项目都丢到C:\dev\myproj这种纯英文无空格的路径下。另外，要是你在开发Flask或Jupyter环境，热重载机制可能会动态重新加载模块，导致断点绑定丢失——只要临时关掉debug=True或者禁用相关插件，通常就能恢复。

launch.json 里最关键的三个字段必须对齐

launch.json这玩意儿，不用把每个参数都背下来，但有三项写错，断点基本就别想正常工作。

第一个是program或module。调试脚本文件（比如main.py）要用"program": "${file}"；如果是包结构运行（比如python -m mypackage.cli），就必须用"module": "mypackage.cli"。这两者不能混用，否则debugpy会找不到入口。

第二个是cwd，即当前工作目录。这个字段直接影响import和文件读写。Django报ModuleNotFoundError，或者程序找不到config.json，十有八九是cwd设错了。建议显式写成"cwd": "${workspaceFolder}/src"，不要依赖默认值。

第三个是env环境变量。调试时，终端里的环境变量默认不会被继承。Django项目必须加"DJANGO_SETTINGS_MODULE": "myproject.settings.dev"，否则启动就崩；FastAPI项目则通常需要"PYTHONPATH": "${workspaceFolder}"才能正常运行。

为什么选对解释器远比装扩展更重要

安装了ms-python.python扩展，只是万&里长征第一步。如果解释器路径指错了，debugpy会启用错误的Python环境来运行代码，然后你可能会看到：第三方库报错、虚拟环境里的包找不到，甚至调试器自己都无法启动。

正确操作很简单：按Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（Mac），输入Python: Select Interpreter，然后选择你项目实际使用的路径。比如./venv/bin/python或C:\myproj\.venv\Scripts\python.exe。状态栏右下角必须显示完整路径，且不能带红色波浪线。如果只显示模糊的“Python 3.9.18 64-bit”，说明根本没真正选中。

conda环境更要留心。确保环境已激活，或者手动指向anaconda3/envs/myenv/python.exe。不要依赖VS Code的自动探测，它常常猜错。

调试时变量看不清？检查 justMyCode 和 console 设置

调试的时候，变量视图一片空白，print()输出不显示，或者无法单步进入函数——这些往往不是代码问题，而是调试配置没打开对应的能力。

"justMyCode"默认是true，意思是只调试你写的代码，跳过site-packages里的第三方库。如果你真想钻进requests.get()的源码里看看，必须把这个设为false。

"console"推荐设为"integratedTerminal"，这样所有输出和输入都会在VS Code内置终端里显示。设成"externalTerminal"在Windows上常因权限问题失败，而且输入会被系统终端吞掉。

还有一种情况：鼠标悬停看不了变量值。先确认没开"showGlobalVariables": false；如果还不行，直接在调试控制台输入type(my_var)或my_var.__dict__来查细节。

说到底，VS Code的断点是“声明式”的——它依赖debugpy在进程启动时完成符号绑定。只要代码路径、模块导入顺序、工作目录这三项中有任何一项和launch.json对不上，断点就会沦为摆设。最麻烦的地方在于：它不会报错，只会沉默地跳过，让你在茫茫代码中反复试探。