如何解决VSCode中Pylance的跨文件夹Python模块导入警告？

问题背景 #

你的项目文件夹结构如下：

/mypythonproject
├── modules
│   └── mycustomfunctions.py
└── script
    └── script.py

在script.py中编写了以下代码，运行正常但Pylance提示Import "mycustomfunctions" could not be resolved警告：

import sys
sys.path.insert(1, '../modules')
from mycustomfunctions import function_a

解决方法 #

• 配置项目根目录为Python路径

  1. 打开VS Code时选择/mypythonproject作为工作区根目录
  2. 在根目录创建.env文件，写入：PYTHONPATH=./
  3. 重启VS Code，Pylance会自动识别modules目录为可导入路径

• 将modules转为Python包并调整导入方式

  1. 在modules目录下创建空文件__init__.py，将其标记为Python包
  2. 修改script.py的导入代码，移除sys.path相关行，改为：

     from modules.mycustomfunctions import function_a
     

  这种方式符合Python包结构规范，Pylance能直接识别模块

• 配置VS Code工作区设置
  在项目根目录的.vscode/settings.json中添加以下配置：

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

  该配置会告诉Pylance额外扫描modules目录，从而解析模块导入

• 使用相对导入（需调整运行方式）
  修改script.py的导入代码为相对导入：

  from ..modules.mycustomfunctions import function_a
  

  运行脚本时需从项目根目录以包模块方式执行：python -m script.script，适合将项目作为完整Python包管理

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