VSCode调试多目录Python项目时相对导入引发ImportError问题

核心原因 #

直接调试framework_module.py时，Python将其视为独立顶层脚本，而非src包的子模块，导致相对导入..无法识别父包结构。而终端运行main_script.py时，项目根目录是Python的工作目录，src被当作合法包，相对导入能正常工作。

解决方案 #

方案1：修改VSCode调试配置（launch.json） #

通过配置调试环境，让Python将src识别为包的一部分：

1. 打开VSCode调试面板，点击「创建launch.json文件」并选择Python环境。
2. 替换为以下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Framework Module",
            "type": "python",
            "request": "launch",
            "module": "src.frameworks.framework_module",
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}

• 使用module参数以包模块方式启动，而非直接运行脚本，确保相对导入基于src包结构解析。
• cwd将工作目录固定在项目根，让Python能正确识别src包。

方案2：通过入口脚本main_script.py启动调试 #

既然终端运行main_script.py无问题，调试时以此为入口：

1. 在launch.json中添加如下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run Main Script",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/main_script.py",
            "cwd": "${workspaceFolder}"
        }
    ]
}

2. 在framework_module.py的目标代码行添加断点，启动调试后，代码执行到断点时即可正常调试，此时相对导入基于src包结构正常工作。

方案3：临时路径补充（仅用于快速测试，不推荐长期使用） #

在framework_module.py开头添加代码，临时将项目根目录加入Python路径，并改用绝对导入：

import sys
from pathlib import Path

# 把项目根目录加入Python路径
sys.path.append(str(Path(__file__).parent.parent.parent))

# 替换为绝对导入
from src.analysis.analysis_module import dummy_analysis
from src.utils.utility_module import dummy_util

此方法会破坏包结构独立性，仅适合临时验证代码逻辑。

注意事项 #

• 确保所有包目录下存在__init__.py文件（你的项目已满足要求）。
• 调试时避免直接右键运行单个模块，需通过配置好的launch.json启动调试。

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