断点显示空心圆且提示“unverified breakpoint”，说明调试器未注册断点，根本原因是调试链路在加载阶段中断：需检查launch.json中"type"是否为"python"、是否存在有效.vscode/launch.json、文件是否已保存、右下角是否显示正确python解释器路径。
断点显示空心圆，鼠标悬停提示“Unverified breakpoint”
这是最直观的失效信号，说明调试器压根没把断点注册进运行时。根本原因不是代码写错了，而是调试链路在加载阶段就断了。
- 检查
launch.json里"type"字段是否为"python"—— 写成"pwa-python"、"coreclr"或直接漏掉，断点都会被静默忽略 - 确认工作区根目录下存在
.vscode/launch.json，且没有被同名文件覆盖（比如多层嵌套目录下有多个.vscode） - 保存文件：VSCode 不会为未保存的
.py文件设置有效断点，哪怕你点了红点，它也只是空心○ - 右下角状态栏必须显示 Python 解释器路径（如
Python 3.11.9 ('venv')），否则launch.json中的"program"字段无法解析${file}
调试启动后程序跑完，断点完全没触发
这说明调试器起来了，但没走到那行——要么路径错、要么没执行、要么被跳过。
-
"program"和"module"别混用："program": "${file}"适用于单文件脚本；若用python -m mypkg.main启动，必须改用"module": "mypkg.main"，否则解释器找不到入口 - 检查
if __name__ == "__main__":是否成立——如果你在模块内部设断点，但该模块是被导入而非直接执行，断点不会命中 - Web 框架（Flask/Django）默认不进视图函数：必须在
launch.json中加"justMyCode": false和"subProcess": true，否则 reload 子进程、路由分发都逃出调试范围 - 插入
breakpoint()测试通路：如果它能中断，说明调试器就位，问题出在断点注册逻辑；如果它也不响，就是环境或配置级断裂
断点进了，但变量为空、调用栈只显示 <module></module>
这通常不是断点失效，而是调试器没拿到源码映射，常见于路径、编码、缓存三类污染。
- 中文路径或含空格的项目路径会导致 AST 解析失败——把项目移到
/tmp/myproj或C:\dev\myproj这类干净路径重试 - 文件头缺编码声明且含中文注释：
# -*- coding: utf-8 -*-必须出现在第一行，否则 debugpy 解析失败，断点虽命中但无上下文 - 删掉所有
__pycache__/和*.pyc：字节码陈旧时，debugpy 可能按旧 AST 绑定断点，实际执行的是新代码 - 验证解释器一致性：在 Debug Console 执行
import sys; print(sys.executable)，和集成终端里which python对比，路径必须一字不差
多环境（poetry/conda/virtualenv）下断点忽灵忽不灵
VSCode 不继承 shell 的激活状态，它只认 python.defaultInterpreterPath 配置的二进制路径。哪怕你在终端里 source venv/bin/activate 后一切正常，VSCode 调试仍可能崩。
- 务必通过命令面板
Ctrl+Shift+P→Python: Select Interpreter选中虚拟环境里的python可执行文件（如./venv/bin/python），不要手动填路径 - poetry 项目要选
.venv/bin/python（Linux/macOS）或.venv\Scripts\python.exe（Windows），不是poetry run python - conda 环境需选
~/miniconda3/envs/myenv/bin/python这类真实路径，不能选 base 环境或未激活的 env - 检查
.vscode/settings.json是否生成了"python.defaultInterpreterPath"，且值与pip list -v显示的 site-packages 路径匹配
复杂点在于：断点是否生效，从来不是单一配置决定的，而是 launch.json + 解释器路径 + 文件编码 + 字节码状态 + 执行入口方式 五者咬合的结果。任何一个齿松了，整个链条就滑脱——尤其当项目从 Flask 切到 CLI 工具、或从 poetry 切到 conda 时，最容易漏掉某个环节。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
