VS Code中Python本地包相对导入报错的解决方法求助

目录结构如下：

workspace_folder
-- module_to_import
--- __init__.py
--- submodule1
---- __init__.py
-- project_currently_working_on

在project_currently_working_on的脚本中尝试用import ..module_to_import做相对导入时，报错：ImportError: attempted relative import with no known parent package。

已尝试的配置及问题：

1. launch.json配置：

// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
    {
        "name": "Python: Module - name module",
        "type": "python",
        "request": "launch",
        // "program": "${file}",
        "cwd": "${workspaceRoot}",
        "env": {"PYTHONPATH": "${workspaceRoot}"},
        "console": "integratedTerminal"
    }
]
}

注释了program字段，运行时未正确指定目标脚本。

2. settings.json配置：

• 添加"python.analysis.extraPaths": ["../module_to_import"]，无效；
• 改为"python.analysis.extraPaths": [".."]后IDE无警告，但运行脚本报ModuleNotFoundError。

3. 工作区配置：

{
    "folders": [
        {
            "path": "."
        }
    ],
    "settings": {
        "python.envFile": "${workspaceFolder}/.env",
        "python.analysis.extraPaths": ["${workspaceFolder}"]
    },  
}

仍出现ModuleNotFoundError，仅IDE能识别模块，运行时报错。

1. 修正launch.json配置，确保PYTHONPATH与运行目标正确 #

相对导入仅适用于包内模块的调用，直接运行脚本时Python不会将其视为包的一部分，因此建议改用绝对导入，同时确保workspace_folder被加入Python的搜索路径：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}", // 取消注释，指定当前运行的脚本
            "cwd": "${workspaceFolder}",
            "env": {"PYTHONPATH": "${workspaceFolder}"}, // 将工作区根目录加入PYTHONPATH
            "console": "integratedTerminal"
        }
    ]
}

之后在脚本中使用绝对导入：

import module_to_import
# 若要导入子模块：
from module_to_import import submodule1

2. 用.env文件全局配置PYTHONPATH #

在workspace_folder根目录创建.env文件，内容如下：

PYTHONPATH=${PYTHONPATH}:${workspaceFolder}

VS Code会自动读取该文件的环境变量，无需每次在launch.json中配置，无论是调试还是终端运行脚本，Python都能找到module_to_import模块。

3. 同步IDE分析路径与运行环境 #

修改settings.json，确保代码提示与运行环境一致：

{
    "python.analysis.extraPaths": ["${workspaceFolder}"]
}

这一步仅解决IDE的代码提示问题，运行时的模块查找仍依赖PYTHONPATH的配置。

为什么相对导入会报错？ #

当直接运行单个Python脚本时，Python会将该脚本所在目录视为顶层模块目录，不会将其识别为某个父包的子模块，因此..这种相对导入语法无法找到对应的父包路径，导致报错。

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