使用VS Code调试器以模块模式运行Python文件报错如何解决

问题根因 #

1. VS Code默认Python调试是直接执行文件，等价于python src/Main.py，不会像-m参数一样把工作目录加入模块搜索路径，也无法识别src作为顶层包，因此触发ModuleNotFoundException。
2. 切换到模块运行模式后填入src.Main.py属于错误配置：Python模块名不需要加.py后缀，错误的模块名会导致进程启动后调试器无法匹配到对应代码，触发连接失败报错。

修复步骤 #

1. 打开VS Code调试面板，点击「创建launch.json文件」，选择Python环境后再选择「Python 模块」调试模板。
2. 当提示输入模块名时，填入src.Main（不带.py后缀），自动生成的配置默认已经正确，你也可以手动修改.vscode/launch.json，参考配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 调试src.Main",
            "type": "python",
            "request": "launch",
            "module": "src.Main",
            "cwd": "${workspaceFolder}",
            "justMyCode": true
        }
    ]
}

3. 保存配置后重新启动调试即可正常导入模块、关联调试进程。

可选替代方案 #

如果你不想用模块模式运行，也可以用默认的文件运行模式，只需要在launch.json的配置中额外添加PYTHONPATH环境变量，把项目根目录加入Python搜索路径即可，示例配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "cwd": "${workspaceFolder}",
            "env": {"PYTHONPATH": "${workspaceFolder}"},
            "justMyCode": true
        }
    ]
}

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