VSCode中如何让Python优先导入本地克隆仓库模块而非系统安装版？

核心原因 #

Python的模块搜索路径sys.path中，系统/usr/lib/python3/dist-packages的优先级高于本地克隆仓库路径，导致导入时优先加载稳定版文件。

具体解决方案 #

1. 使用虚拟环境（推荐） #

创建并激活项目专属的虚拟环境，彻底隔离系统全局包：

• 在项目根目录打开终端，执行：

  python3 -m venv .venv
  source .venv/bin/activate  # Linux/macOS
  # Windows: .venv\Scripts\activate
  

• 在VSCode右下角点击Python环境选择器，切换到刚创建的.venv环境。
• 安装项目依赖（不要安装系统稳定版的APP包），此时Python只会从虚拟环境和本地项目路径导入模块。

2. 修改VSCode工作区设置，提升本地路径优先级 #

• 打开VSCode的工作区设置（Ctrl+, 或 Cmd+,，选择"工作区"标签）。
• 搜索python.analysis.extraPaths，点击"编辑 in settings.json"，添加本地克隆仓库的根路径：

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

  这会让VSCode的Python分析器优先识别本地项目文件，同时运行时也会优先加载该路径下的模块。

3. 配置launch.json（针对调试场景） #

如果调试时出现该问题，修改调试配置文件：

• 打开"运行和调试"面板，点击"创建launch.json文件"，选择Python环境。
• 在configurations中添加env字段，设置PYTHONPATH为本地项目根路径：

  {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Python: 当前文件",
        "type": "python",
        "request": "launch",
        "program": "${file}",
        "console": "integratedTerminal",
        "env": {
          "PYTHONPATH": "${workspaceFolder}"
        }
      }
    ]
  }
  

  PYTHONPATH会让Python运行时优先搜索该路径下的模块。

4. 临时代码级修复（不推荐长期使用） #

在项目入口文件最顶部添加以下代码，强制将本地路径插入sys.path最前面：

import sys
from pathlib import Path

# 添加项目根路径到sys.path首位
sys.path.insert(0, str(Path(__file__).parent))

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