VS Code中launch.json配置与Python调试问题求助

一、launch.json 必备参数含义与工作逻辑 #

拆解你用到的核心参数，并补充常用必备项：

• "version": "0.2.0"：调试配置文件的版本标识，不同版本对应不同调试器特性，保持默认即可。
• "name": "Python: Current File"：调试配置的显示名称，会出现在VS Code调试面板的下拉列表，方便区分多配置场景。
• "type": "debugpy"：指定调试器类型，Python官方目前统一用debugpy替代旧版ptvsd。
• "request": "launch"：调试模式，launch是直接启动目标程序进行调试，另一种attach用于附加到已运行的进程。
• "program": "${file}"：指定调试入口文件，${file}是VS Code内置变量，指代当前激活的打开文件。
• "console": "integratedTerminal"：调试输出的终端类型，integratedTerminal用VS Code内置终端，externalTerminal调用系统终端，internalConsole用调试专属控制台。
• "justMyCode": false：控制是否仅调试用户自有代码，设为false可调试第三方库或标准库代码。
• "cwd": "${workspaceFolder}/tree/branch1/"：程序运行的工作目录，${workspaceFolder}对应当前打开的工作区根目录。
• 额外常用必备参数：
  • "env"：设置环境变量，比如通过PYTHONPATH指定模块搜索路径，这是解决导入问题的关键；
  • "args"：传递给目标程序的命令行参数，调试带参数的脚本时会用到。

二、模块导入问题的核心原因 #

1. pytest与直接Python执行的差异 #

pytest运行时会自动将测试文件所在目录的父目录（即你的branch1目录）加入sys.path，此时leaf2作为branch1下的子模块被识别，所以from leaf2.pyhelp import something能正常找到模块。
而直接在leaf2目录执行python pytest.py时，Python只会把当前目录（leaf2）加入sys.path，leaf2本身不是任何父级模块的一部分，自然找不到leaf2.pyhelp。你说打印sys.path二者一致，大概率是打印时机不对——pytest会在启动后动态修改sys.path，需要在导入语句之前打印才能看到真实差异。

2. VS Code调试的问题 #

你的launch.json将cwd设为branch1目录，理论上Python会把branch1加入sys.path，但报错说明两个可能：

• Poetry虚拟环境的PYTHONPATH被覆盖，导致branch1未被正确加入模块搜索路径；
• 导入语句逻辑矛盾：当cwd是branch1时，from leaf2.pyhelp import something是找branch1/leaf2/pyhelp.py，这本身是正确的，但如果你的虚拟环境没有正确加载，或者sys.path被其他配置干扰，就会报错。

三、具体解决方案 #

方案1：修改导入语句（最推荐） #

既然pytest.py和pyhelp.py在同一leaf2目录下，直接用同目录导入更合理：

# 替换原有导入语句
from pyhelp import something

如果要按包结构导入，给leaf2目录添加空的__init__.py文件，将其标记为Python包，然后用相对导入：

from .pyhelp import something

方案2：调整launch.json配置 #

若不想修改代码，通过env参数手动将branch1加入PYTHONPATH，同时调整cwd匹配终端执行场景：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false,
            "cwd": "${workspaceFolder}/tree/branch1/leaf2/",
            "env": {
                "PYTHONPATH": "${workspaceFolder}/tree/branch1"
            }
        }
    ]
}

• cwd设为leaf2，和你终端执行的工作目录一致；
• PYTHONPATH添加branch1，让Python能识别leaf2作为模块，确保导入语句生效。

方案3：修复终端直接执行命令 #

在leaf2目录执行时，临时将branch1加入PYTHONPATH：

PYTHONPATH=../.. python pytest.py

或者先导出环境变量再执行：

export PYTHONPATH=../..
python pytest.py

四、Poetry环境的适配要点 #

确保VS Code使用Poetry创建的虚拟环境：

1. 打开命令面板（Ctrl+Shift+P），执行Python: Select Interpreter，选择Poetry虚拟环境（通常位于~/.cache/pypoetry/virtualenvs/路径下）；
2. 可在.vscode/settings.json中添加默认解释器配置，避免每次切换：

{
    "python.defaultInterpreterPath": "/path/to/your/poetry/env/bin/python"
}

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