VSCode + Python 开发踩坑：虚拟环境不在项目根目录导致包无法识别该怎么办

原创于 2025-09-16 21:22:18 发布 · 1.1k 阅读

CC 4.0 BY-SA版权

文章标签：

最近在学习Dify ，尝试自己使用源码启动项目并进行二次开发。

我按照Dify的官方文档说明使用uv在项目的api目录下安装了Python虚拟环境，但是在VSCode右下角的Python解释器选择中却无法像conda管理的虚拟环境一样直接找到并选中，需要手动选择解释器存在，而且我在手动设置之后VSCode无法识别安装在该虚拟环境下的的第三方包。

折腾了一圈终于找到了解决方案，在此记录下来，希望能帮到同样踩坑的小伙伴。

项目结构及场景复现

Dify 是前后端分离项目，项目的目录结构大致长这样：

.
├── api/        # 后端 Python 代码
    └── .venv/    # 存放虚拟环境
        ├── bin/python    # python解释器路径
        └── lib/python3.12/site-packages/    # 虚拟环境中安装的第三方包路径
├── web/        # 前端NextJS代码

我操作的步骤如下：

使用VSCode打开整个项目
在api目录下使用uv sync --dev安装项目依赖
点击VScode右下角解释器选择按钮，并选择“输入解释器路径……”，之后选择：
```
~/dify/api/.venv/bin/python
```
打开 api 下的任意 Python 文件。

结果发现：
状态栏可以显示出正确的Python版本，但不显示出虚拟环境的名称，如图：
截屏2025-09-16 20.47

同时代码文件中import pandas as pd、import docx 下面都是一片波浪线，也无法查看第三方库中函数的文档。

截屏2025-09-16 20.58

查看解释器指向的路径，发现其实际路径指向了opt/homebrew/bin/python3.12，这是一个系统层面的路径，和项目无关，项目中的解释器实际上只是一个软链接，并没有针对对应的虚拟环境索引其中安装的Python包。

背后的原因

根据网上的搜索，发现VS Code 的 Python 支持分两部分：

解释器（Interpreter）
决定运行或调试代码时用哪个 python，只需要制定bin/python路径即可。
语言服务器（Pylance）
负责语法高亮、类型检查、自动补全等，需要去索引解释器的 site-packages 才知道有哪些模块。

我原本以为选对了解释器就等于“语言服务器会自动索引和这个解释器相关的site-packages”，其实不对。

Pylance 只会自动扫描以下位置：
- 当前工作区根目录里的 .venv、env 等常见名称；
- Conda 环境列表；
- 系统 PATH。

如果虚拟环境藏在像非根目录下的api/.venv里，即便设置了解释器路径，但Pylance 不会主动去找对应的site-packages 路径。因此VS Code 也就无法索引到当前虚拟环境下安装了哪些包，于是就会显示波浪线。

解决方案

方法一：在项目的`settings.json` 中设置 `python.defaultInterpreterPath`

对于单个项目，最简单的办法是在项目根目录新建（或修改） .vscode/settings.json，在里面加上配置：

{
    "python.defaultInterpreterPath": "./api/.venv/bin/python"
}

这里的路径可以写相对路径。

这条配置会告诉 VS Code： “这个工作区的默认解释器是这里，顺便把它的 site-packages 纳入分析。”

该方法适用于一个项目只用一个虚拟环境，以及环境路径是固定的情况。

保存后再点击右下角的解释器选择按钮，可以看到多出了一个选项使用python.defaultInterpreterPath设置中的Python，如图：
截屏2025-09-16 20.54.17

选中这个选项后，右下角的Python解释器不光显示出Python版本，还显示出对应的Python虚拟环境的名称，如图：
截屏2025-09-16 20.57.02

由此我也想到，在团队协作时，.vscode/settings.json 是不是也可以提交到仓库，这样大家可以共享解释器配置，不用每个人再去手动配置。

方法二：在VSCode设置中配置`Python: Venv Folders`

也可以在 VSCode软件的设置中配置Python: Venv Folders，如果找不到，可以搜索。在Python: Venv Folders中增加路径/absolute/path/dify/api/.venv（这里的路径需要写绝对路径），如图：

截屏2025-09-16 21.06

这样 Pylance 会扫描添加的路径下的虚拟环境，索引它们的 site-packages。之后就可以在Python解释器选择界面的最下方找到对应的虚拟环境：

截屏2025-09-16 21.13