VSCode/Pylance提示‘Import could not be resolved’：文件移至根目录后导入告警

问题场景 #

我在Windows 11系统上使用VSCode开发Python项目，近期将项目中sub_folder下的所有文件移至根目录，以便直接从根目录执行代码。迁移后执行python -m root_folder.main时代码可正常运行，但VSCode中导入语句被黄色高亮，提示：

Import "root_folder.package2.script2" could not be resolved

迁移前后项目结构 #

迁移前

root_folder/
    sub_folder/
        package1/
            __init__.py  # empty
            script1.py
        package2/
            __init__.py  # empty
            script2.py
        main.py

迁移后

root_folder/
    package1/
        __init__.py  # empty
        script1.py
    package2/
        __init__.py  # empty
        script2.py
    main.py

导入语句变化 #

迁移前script1.py中的导入语句：

from sub_folder.package2.script2 import example_func

迁移后修改为：

from root_folder.package2.script2 import example_func

解决方法 #

1. 修正导入语句（推荐） #

当使用python -m root_folder.main运行时，root_folder会被当作顶层包，此时无需在导入语句中添加root_folder前缀，直接从子包导入即可：

from package2.script2 import example_func

这种写法符合Python包的导入规范，Pylance能自动识别路径，不会再出现高亮提示。

2. 配置VSCode让Pylance识别根目录 #

如果不想修改导入语句，可通过配置让VSCode把root_folder加入模块搜索路径：

• 打开VSCode并将root_folder设为当前工作区
• 按下Ctrl+Shift+P打开命令面板，输入Python: Select Interpreter，选择项目使用的Python解释器（虚拟环境或系统环境均可）
• 在root_folder下新建.vscode/settings.json文件，写入以下内容：

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

该配置会告诉Pylance将当前工作区目录添加到Python模块搜索路径中，从而识别root_folder开头的导入语句。

3. 验证生效 #

配置完成后，按下Ctrl+Shift+P输入Reload Window重启VSCode窗口，此时黄色高亮的导入提示应该会消失。

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