VS Code + Pylance 导入波浪线问题终极解决手册

（以 RagFlow 项目为例，通用 Python 项目）
一、问题现象
代码中import语句出现黄 / 红波浪线，提示：
“无法解析导入 xxx（reportMissingImports）”
终端运行代码无报错、依赖已装在虚拟环境中

二、核心原因
Pylance（VS Code Python 语言服务）未正确识别：
虚拟环境的site-packages依赖；
项目的自定义模块路径。

三、分场景解决方案
场景 1：第三方依赖波浪线（如 langfuse、trio）
步骤：
确认依赖安装：

bash
运行
# 进入项目根目录+激活虚拟环境
cd 项目根目录 && source .venv/bin/activate
# 验证依赖（以trio为例）
uv pip show trio  # 输出Location需包含.venv

强制 Pylance 识别 site-packages：
按Cmd+Shift+P → 打开Preferences: Open Workspace Settings (JSON)
写入（替换实际路径）：

json
{
    "python.analysis.extraPaths": [
        "项目根目录/.venv/lib/python3.x/site-packages"
    ],
    "python.pythonPath": "项目根目录/.venv/bin/python"
}

刷新索引：Cmd+Shift+P → 执行Python: Refresh IntelliSense

场景 2：自定义模块波浪线（如 from api.db...）
步骤：
项目根目录新建.env 文件：
ini
PYTHONPATH=.:${PYTHONPATH}
安装插件：VS Code 扩展商店搜索Python Environment Variables并安装。
重启 VS Code：关闭窗口后重新打开项目。

场景 3：缓存导致的顽固波浪线
步骤：
关闭所有 VS Code 窗口。
清理缓存（Mac 终端）：

bash
运行
rm -rf ~/Library/Application\ Support/Code/User/workspaceStorage/*/ms-python.vscode-pylance/

重新打开项目：
重新选择虚拟环境 → 刷新 IntelliSense。

四、验证标准
代码波浪线消失；
终端运行代码无ModuleNotFoundError；
uv pip show 依赖名的 Location 包含.venv。

五、预防措施
用uv venv创建项目专属虚拟环境；
项目根目录保留.env文件；
依赖安装统一用uv pip install。