VS Code调试多文件Python项目 断点命中显示空白文件异常

两类异常（跨文件普通断点不命中、断点命中弹出内容不匹配的假文件）的核心诱因集中在工作区加载错误、调试配置错误、路径映射错位、缓存冲突四类，按以下顺序排查即可解决： #

基础配置校验（解决90%以上的同类问题） #

• 必须以项目根目录为工作区启动：不要单独打开单个入口.py文件就启动调试，通过「文件-打开文件夹」选中项目最外层根目录加载完整工作区。单文件模式下调试器无法索引同项目其他文件的源码路径，是断点失效、弹假文件的最高发原因。
• 匹配正确的Python解释器：按Ctrl+Shift+P（Windows/Linux）/Cmd+Shift+P（Mac）调出命令面板，执行Python: Select Interpreter，选中项目实际运行使用的虚拟环境/系统Python解释器，避免调试器加载到其他环境下的同名包文件。
• 修正launch.json调试配置：点击调试面板的齿轮图标打开.vscode/launch.json，删除错误配置的pathMappings项（本地调试不需要手动配置路径映射，配错会直接指向错误缓存文件），本地脚本调试可直接使用以下最简有效配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 调试当前项目",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/你的入口文件路径.py",
            "justMyCode": false,
            "cwd": "${workspaceFolder}"
        }
    ]
}

重点注意：justMyCode必须设置为false，默认值true会让调试器跳过未被识别为「当前工作区用户代码」的文件，直接导致跨文件普通断点无法命中；cwd固定为工作区根目录，避免相对路径导包时加载到其他位置的同名文件。

缓存与冲突清理 #

如果配置正确后依然弹出内容、行号不匹配的空白假文件，按以下步骤清理缓存：

• 关闭VS Code，删除项目目录下所有__pycache__文件夹、.pyc后缀的字节码缓存文件
• 重新打开VS Code后按Ctrl+Shift+P调出命令面板，执行Developer: Reload Window重载窗口，清除调试器留存的旧路径映射缓存
• 禁用非官方Python调试插件：仅保留微软官方发布的Python、Python Debugger两个插件，卸载/禁用其他第三方Python调试类插件，避免多插件钩子冲突导致路径解析错误。

特殊场景排查 #

如果以上操作后问题依然存在：

• 断点命中时查看调试控制台顶部显示的当前执行文件绝对路径，和你本地打开的源码文件路径做对比，如果路径不一致说明导包逻辑引用了其他目录下的同名文件，调整项目导包路径即可
• 检查项目所在路径是否包含中文、特殊符号、空格，部分旧版本debugpy对非ASCII路径的解析存在兼容bug，将项目移动到纯英文无空格的路径下即可修复。

内容的提问来源于stack exchange，提问作者Luxsal