VSCode Python .embed 嵌入式环境黄色波浪线问题

.embed 是 Python embeddable 免安装绿色版，没有注册表、没有系统PATH，VSCode 的 Python 扩展默认不会自动识别它，能运行但编辑器报黄色波浪线（pylance 找不到包） ，这是最典型现象：终端运行正常，编辑器提示 cannot import xxx。

根本原因

VSCode Python/Pylance 没有选中你的 .embed 解释器；
embeddable python 的 python3xx._pth 文件没有正确配置 site‑packages 路径；
Pylance 语言服务器的搜索路径没有包含第三方库目录。

步骤1：在VSCode选中embed里的python.exe

Ctrl+Shift+P → Python: Select Interpreter
点击 Enter interpreter path...
选中你的 .embed 目录下的 python.exe（例如 ./python-3.11.9-embed-amd64/python.exe）

⚠️ 很多人以为选完就完事，但 embeddable 默认关闭 site 模块，Pylance 依旧找不到库。

步骤2：修复 `python3xx._pth`（embed环境关键）

打开embed目录下的 python311._pth（版本号随你python版本变化）

示例原始文件：

复制代码

python311.zip
.
# import site

把 # import site 的注释去掉：

复制代码

python311.zip
.
import site

不加这行，embed Python 不会加载 site‑packages，pip装的库都看不到，不光编辑器，部分脚本也会找不到包。
安装包：使用embed内的python.exe执行pip

shell 复制代码

./python.exe -m pip install xxx

第三方库会安装到 ./Lib/site-packages

步骤3：配置 Pylance 搜索路径（解决黄色波浪线核心）

在项目根目录新建/编辑 .vscode/settings.json

json 复制代码

{
    // 指定解释器
    "python.defaultInterpreterPath": "${workspaceFolder}/python-3.11.9-embed-amd64/python.exe",
    // 告诉pylance去哪里找库，填写embed的site-packages绝对/相对路径
    "python.analysis.extraPaths": [
        "${workspaceFolder}/python-3.11.9-embed-amd64/Lib/site-packages"
    ],
    // 关闭不必要的虚环境探测
    "python.venvPath": [],
    "python.terminal.activateEnvironment": false
}

${workspaceFolder} 代表项目根目录，用相对路径方便团队同步。
修改完设置，Ctrl+Shift+P → Python: Restart Language Server，重启Pylance。

步骤4：检查pip安装位置是否正确

打开embed的python.exe，执行：

python 复制代码

import site
print(site.getsitepackages())

输出应该包含 .../Lib/site-packages，如果是空列表，说明上面的 _pth 文件没改对。

常见坑

坑1：修改了_pth，但pip还是装到用户目录

embed python 默认不会使用用户site-packages，执行pip必须显式调用本环境的python.exe：

shell 复制代码

# ✅正确
./python.exe -m pip install numpy

# ❌错误，直接调用系统pip，会装到系统python
pip install numpy

坑2：黄色波浪线还在，代码运行正常

说明运行时解释器是对的，Pylance分析路径不对。

确认 python.analysis.extraPaths 路径真实存在；
重启语言服务器；
不要混用系统python的pylance缓存：Ctrl+Shift+P > Clear Editor History

坑3：embed没有Lib/site-packages文件夹

刚解压的embed没有这个文件夹，执行一次pip安装包就自动生成。

最小化可直接复制的settings.json模板

json 复制代码

{
    "python.defaultInterpreterPath": "${workspaceFolder}/python-3.12.0-embed-amd64/python.exe",
    "python.analysis.extraPaths": [
        "${workspaceFolder}/python-3.12.0-embed-amd64/Lib/site-packages"
    ],
    "python.analysis.useLibraryCodeForTypes": true,
    "python.terminal.activateEnvironment": false
}

补充：如果不想提交.vscode到git

把 .vscode/settings.json 加到 .gitignore，也可以在用户全局settings配置，但推荐项目级配置，保证项目开箱即用。

如果你愿意，可以贴出你的目录结构，我可以直接给你适配好的settings内容。

VSCode Python .embed 嵌入式环境黄色波浪线问题