Vscode 中 python模块的导入问题

VSCode配置PYTHONPATH解决Python模块导入问题

问题描述

在使用VSCode开发Python项目时，经常会遇到模块导入错误的问题。当项目结构较为复杂，包含多个层级的目录时，Python解释器可能无法正确找到自定义模块，导致ModuleNotFoundError或ImportError。

问题原因

Python解释器在导入模块时，会按照以下顺序搜索模块：

1. 当前脚本所在目录
2. PYTHONPATH环境变量中指定的目录
3. Python安装路径中的标准库目录

查看当前Python解释器的模块搜索路径

import sys
paths = sys.path
# 遍历当前Python解释器的模块搜索路径列表
for path in paths:
    print(path)

终端输出信息：

(base) PS E:\Projects\OCR-sdk> (D:\ProgramData\Anaconda3\shell\condabin\conda-hook.ps1) ; (conda activate base)
(base) PS E:\Projects\OCR-sdk> & D:\ProgramData\Anaconda3\python.exe e:/Projects/OCR-sdk/tests/path.py
e:\Projects\OCR-sdk\tests
D:\ProgramData\Anaconda3\python313.zip
D:\ProgramData\Anaconda3\DLLs
D:\ProgramData\Anaconda3\Lib
D:\ProgramData\Anaconda3
D:\ProgramData\Anaconda3\Lib\site-packages
D:\ProgramData\Anaconda3\Lib\site-packages\win32
D:\ProgramData\Anaconda3\Lib\site-packages\win32\lib
D:\ProgramData\Anaconda3\Lib\site-packages\Pythonwin
(base) PS E:\Projects\OCR-sdk> 

路径仅包含当前python文件、系统环境变量和当前python环境目录，当前项目根目录不在Python的模块搜索路径中时，所以跨目录的模块导入会失败。

解决方法

通过配置VSCode的集成终端环境变量，将项目根目录添加到PYTHONPATH中，让Python解释器能够正确找到项目中的所有模块。

配置步骤

修改用户配置，通过ctrl+shift+p 打开用户配置文件：

也可以修改当前项目的工作区配置文件\.vscode\settings.json

在配置文件中添加如下配置：

{
  "terminal.integrated.env.windows": {
    // 设置 PYTHONPATH 环境变量为当前工作区根目录
    "PYTHONPATH": "${workspaceFolder}"
  }
}

配置说明

• terminal.integrated.env.windows：针对Windows系统的集成终端环境变量配置
• PYTHONPATH：Python解释器用于搜索模块的环境变量
• ${workspaceFolder}：VSCode内置变量，表示当前工作区的根目录路径

其他平台配置

windows/Linux/macOS配置

{
  "terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}"
  },
  "terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}"
  },
  "terminal.integrated.env.osx": {
    "PYTHONPATH": "${workspaceFolder}"
  }
}

验证配置是否生效

再次查看模块搜索路径

```python
import sys
paths = sys.path
for path in paths:
    print

为了防止修改后未立即生效，可以在新终端里再次测试或者直接重启Vscode

(base) PS E:\Projects\OCR-sdk> & D:\ProgramData\Anaconda3\python.exe e:/Projects/OCR-sdk/tests/path.py
e:\Projects\OCR-sdk\tests
E:\Projects\OCR-sdk
D:\ProgramData\Anaconda3\python313.zip
D:\ProgramData\Anaconda3\DLLs
D:\ProgramData\Anaconda3\Lib
D:\ProgramData\Anaconda3
D:\ProgramData\Anaconda3\Lib\site-packages
D:\ProgramData\Anaconda3\Lib\site-packages\win32
D:\ProgramData\Anaconda3\Lib\site-packages\win32\lib
D:\ProgramData\Anaconda3\Lib\site-packages\Pythonwin

如果配置成功，那么项目根目录（例如：E:\Projects\OCR-sdk）应该出现在sys.path的输出中。

注意

1. 重启终端：修改配置后需要重新打开集成终端才能生效
2. 多项目支持 ：每个项目可以有独立的.vscode/settings.json配置
3. 路径分隔符 ：在Windows中使用分号;分隔多个路径，在macOS/Linux中使用冒号:

扩展配置

如果需要添加多个路径到PYTHONPATH：

{
  "terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder};${workspaceFolder}\\src;${workspaceFolder}\\lib"
  }
}