如何在VSCode中调试Python并解决本地包导入解析失败问题

问题核心 #

你的本地Python环境（含VSCode的Pylance插件）未将.python_packages\lib\site-packages目录纳入模块搜索路径，导致无法识别该目录下的库；而Azure Functions部署时会自动读取该路径的包，因此线上运行正常。

解决办法 #

方法1：代码开头手动添加路径（快速生效） #

在Python文件最顶部（所有import语句之前）加入以下代码，手动把目标目录加入Python的搜索路径：

import sys
import os

# 拼接出包所在的绝对路径
package_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), '.python_packages', 'lib', 'site-packages')
sys.path.append(package_path)

保存文件后，Pylance即可识别对应库。

方法2：配置VSCode工作区设置（全局生效） #

1. 按下Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac），输入Preferences: Open Workspace Settings (JSON)打开工作区配置文件。
2. 添加以下配置，告知Pylance额外的模块搜索路径：

{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/.python_packages/lib/site-packages"
  ]
}

保存后，通过Ctrl+Shift+P输入Python: Restart Language Server重启语言服务，导入错误即可消失。

方法3：使用虚拟环境（长期规范方案） #

如果项目未使用虚拟环境，可创建虚拟环境并同步依赖：

1. 终端创建虚拟环境：

# Windows
python -m venv .venv

# Mac/Linux
python3 -m venv .venv

2. 激活虚拟环境：

# Windows（PowerShell）
.venv\Scripts\Activate.ps1

# Windows（Cmd）
.venv\Scripts\activate.bat

# Mac/Linux
source .venv/bin/activate

3. 安装依赖：
   如果有requirements.txt，直接执行：

pip install -r requirements.txt

如果没有，先从.python_packages导出依赖：

pip freeze > requirements.txt

再执行安装命令。最后选择该虚拟环境作为VSCode的Python解释器，即可正常识别所有包。

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