VSCode + Python 开发踩坑：虚拟环境不在项目根目录导致包无法识别该怎么办
最近在学习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版本，但不显示出虚拟环境的名称，如图：
同时代码文件中import pandas as pd、import docx 下面都是一片波浪线，也无法查看第三方库中函数的文档。
查看解释器指向的路径，发现其实际路径指向了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，如图：
选中这个选项后，右下角的Python解释器不光显示出Python版本，还显示出对应的Python虚拟环境的名称，如图：
由此我也想到，在团队协作时，.vscode/settings.json 是不是也可以提交到仓库，这样大家可以共享解释器配置，不用每个人再去手动配置。
方法二：在VSCode设置中配置Python: Venv Folders
也可以在 VSCode软件的设置 中配置Python: Venv Folders，如果找不到，可以搜索。在Python: Venv Folders中增加路径/absolute/path/dify/api/.venv（这里的路径需要写绝对路径），如图：
这样 Pylance 会扫描添加的路径下的虚拟环境，索引它们的 site-packages。之后就可以在Python解释器选择界面的最下方找到对应的虚拟环境：
