VSCode安装Step-by-step调试 逻辑排查必备VSCode单步执行

VSCode单步调试前需确保Microsoft官方Python扩展启用并重启，正确配置launch.json中program路径或模块名称，Web框架关闭重载，断点设在可执行语句，Watch表达式须符合当前作用域。

VSCode单步执行前，必须确认 Python 扩展已启用

按下F5毫无反应、断点图标变成了空心圆、右下角也看不到Python解释器的版本信息——这些信号再明确不过了：你的Python扩展要么没装对，要么根本没启用。这里有个关键点：只有Microsoft官方的ms-python.python扩展才提供完整的调试能力；而ms-python.pylance只负责代码补全和类型检查，它可没法帮你调试。

具体操作，其实就三步：

• 打开扩展面板（快捷键Ctrl+Shift+X），搜索“Python”，认准发布者是Microsoft、名称包含“Python”、并且状态显示为“已启用”。
• 安装或启用后，必须重启VSCode，否则F5很可能依然无效。
• 最后，别忘了点击底部状态栏的Python版本号，手动选择正确的解释器，尤其是在使用虚拟环境的时候。

launch.json 配置错一个字段，断点就永远不命中

断点位置设得再精准，如果launch.json配置文件里program路径写错了，或者误用了module模式，那么VSCode启动的调试进程，跟你正在编辑的文件可能就完全不是一回事——断点自然形同虚设。

下面这几个配置陷阱，是新手最容易踩的坑：

• program字段的路径必须是相对于${workspaceFolder}（工作区根目录）的。比如你的脚本在src/main.py，这里就应该写"program": "src/main.py"，写成./src/main.py或者绝对路径都可能出问题。
• 当使用module模式时（例如运行python -m http.server），这里填的是模块名，而不是文件名。正确写法是"module": "http.server"，而不是"http.server.py"。
• 对于Flask、FastAPI这类Web框架，务必在代码中关闭重载功能（设置debug=False, use_reloader=False），否则调试器无法正确附加到实际运行的子进程上。

单步执行（F10/F11）停在哪，取决于你断点设在哪一行

Python调试器的断点只在“可执行语句”上生效。如果你把断点设在函数定义行（def foo():）、类定义行（class Bar:）、空行或者注释行，VSCode会自动将其“挪”到下一行。但这个自动挪动并不总是靠谱，尤其是在遇到装饰器、多行字典或者复杂的生成器表达式时。

更稳妥的做法是：

• 尽量把断点设在有实际“副作用”的语句上，比如变量赋值（x = 1）、函数调用（print()）、return语句或者yield表达式。
• 避免在@decorator装饰器下方紧跟着的def行上设断点。因为实际执行时，断点会落在函数体的第一行，这很容易让人误判程序的执行入口。
• 将鼠标悬停在断点的红点上，查看提示信息。如果显示“断点未命中”，优先检查launch.json配置；如果显示“已禁用”，则右键点击断点，检查是否不小心添加了条件或命中次数限制。

Watch 表达式输 user.name 报错？不是语法问题，是作用域不对

Watch窗口并不是一个万能的REPL环境，它只能对当前调用栈帧（stack frame）中存在的变量进行求值。举个例子，你在函数外部定义的user对象，一旦单步执行进入另一个函数内部，这个user变量就不在当前作用域里了——此时在Watch里输入user.name，必然会引发ReferenceError。

遇到这类问题，可以这样排查：

• 首先，展开左侧的Variables（变量）面板，找到目标对象的具体层级，然后右键点击它，选择“复制表达式”，就能得到类似locals.user.name的完整路径，再将其粘贴到Watch窗口中。
• 对于复杂的嵌套对象，建议不要手动输入，很容易漏掉locals、self、args这类必要的前缀。
• 另外要知道，某些表达式（比如dict.keys()）在调试器环境下可能返回不可迭代的对象，Watch窗口显示Cannot evaluate expression是调试器本身的限制，通常不是代码的bug。

话说回来，调试过程中最让人头疼的，往往不是不知道按F10进行单步跳过，而是断点压根就没进入你预想的执行流程。这多半是因为launch.json里定义的启动方式，和你平时手动在终端运行的命令不一致，或者是Web框架在后台偷偷fork了新进程。一个有效的检查方法是：先盯紧调试控制台输出的第一行信息，确认VSCode真正运行的，就是你刚刚修改过的那份代码。