你已经 source .venv/bin/activate、pip install -r requirements.txt，在终端里跑得好好的。同一个项目用 Cursor 打开，import 全是红线，Pylance 报 Import "fastapi" could not be resolved，Composer 还热心建议你 pip install fastapi，明明已经装了。状态栏写着 Python 3.11.7 64-bit，指向 /usr/local/bin/python3 而不是 .venv/bin/python。这是 Python 扩展的解释器发现问题，不是真正的包安装问题，而它会一路传染到 lint、类型检查、agent 修改、运行调试。
最快的修法： 按 Cmd+Shift+P（Windows/Linux 为 Ctrl+Shift+P），运行 Python: Select Interpreter，选 “Enter interpreter path…”，粘贴 .venv/bin/python 的绝对路径（Windows 上是 .venv\Scripts\python.exe）。然后执行 Python: Restart Language Server。这一步能解决大约 80% 的情况。如果不奏效，往下按”分桶”排查。
2026 年有一个变化容易让人栽跟头：微软的 Python Environments 扩展（ms-python.vscode-python-envs）已于 2026 年 2 月正式发布（GA），现在是 Python 扩展默认的环境管理器。解释器选择有一部分从状态栏挪进了专门的 Python 面板 / 树视图。如果状态栏看着没错、import 却还红，那么面板里的活跃环境可能和状态栏不一致。见下面的第 7 条。
先看你属于哪一桶
做一项快速检查，再跳到对应原因。
| 快速检查 | 你看到的现象 | 最可能的原因 |
|---|---|---|
| 状态栏 / Python 面板里的解释器 | 指向 /usr/local/bin 或 /opt/homebrew/bin | 原因 1：缓存了错误解释器 |
Python: Select Interpreter 列表 | 你的 venv 压根不在列表里 | 原因 2 或 3：venv 在根目录外或被工具托管 |
conda info --envs 对比选择器 | 环境存在但显示成 (base) | 原因 4：conda 没接好 |
集成终端 echo $PATH | 缺了 .zshrc 里的条目 | 原因 5：GUI 的 PATH 继承 |
| 同一窗口、不同文件 | 一个文件能解析、另一个不行 | 原因 6：多根不一致 |
| 状态栏正确但 import 仍红 | Python 面板里活跃环境不一样 | 原因 7：Python Environments 面板分歧 |
常见原因
按 venv 识别失败的发生频率排序。
1. 第一次打开时 Cursor 挑错了解释器
Python 扩展在 workspace 打开时扫描可用解释器，把选择缓存到 .vscode/settings.json。如果你是在 Cursor 第一次打开项目之后才创建的 venv，或者 venv 路径不标准，缓存里会一直指向系统 Python，再也不更新。
如何判断：.vscode/settings.json 里 "python.defaultInterpreterPath" 指向 /usr/local/bin/python 或 /opt/homebrew/bin/python3，而不是 .venv/bin/python。
2. venv 不在工作区根目录下
如果 venv 在 ~/.virtualenvs/myproj（virtualenvwrapper）或者兄弟目录里，扩展的自动扫描就找不到。只有 ./.venv、./venv、./env 会被自动发现。
如何判断：集成终端里 which python 是对的 venv，但状态栏的解释器选择列表里压根没有它。
3. Poetry / PDM / Hatch / uv 管理的 venv
poetry（默认）和 pdm 会把 venv 放在集中缓存（~/.cache/pypoetry/virtualenvs/...）。Cursor 的 Python 扩展只有在显式给出路径时才会识别。（uv 不一样：截至 2026 年 6 月，uv sync 和 uv venv 会在项目根目录创建 ./.venv，所以 uv 的 venv 通常能被自动发现；缓存里放的是下载来的解释器，而不是项目 venv。）
如何判断：poetry env info --path 返回的路径，在解释器选择器里看不到。
4. Conda 环境没有在 Cursor 启动器里激活
Conda 环境需要启用 Anaconda 支持，或显式设置 python.condaPath。否则环境出现时 base prefix 是错的，import 也会失败。
如何判断：conda info --envs 显示你的环境存在，但 Cursor 里选中后状态栏仍写 (base)。
5. Cursor 与终端的 shell PATH 不同
Cursor 从启动它的父进程继承 PATH——Finder、Dock、Spotlight。如果你的 venv 激活依赖 .zshrc/.bashrc，那么 GUI 启动 Cursor 时这些 rc 文件根本不会执行。
如何判断：打开集成终端，echo $PATH 少了你在 .zshrc 里写的条目。新开一个 Terminal.app 则一切正常。
6. 多根 workspace，但活跃的那个根没有 Python 配置
multi-root workspace 里每个文件夹都可以有自己的 Python 解释器。状态栏跟着当前编辑器文件所属的根走——在不同根的文件之间切换会悄悄换解释器。
如何判断：同一个 Cursor 窗口里，一个文件 import 没问题，另一个就红线。点击不同文件时状态栏解释器在变。
7. Python Environments 面板里的活跃环境不一样
自 Python Environments 扩展（ms-python.vscode-python-envs）于 2026 年 2 月正式发布（GA）后，它成了默认的环境管理器，并通过活动栏里自己的 Python 树视图接管了大部分解释器选择工作。状态栏选择器和这个面板可能不一致，尤其是刚升级之后：状态栏可能显示 .venv，而面板里用于分析的活跃环境仍是系统 Python。
如何判断：打开 Python 面板（活动栏，或 Cmd+Shift+P -> Python: Focus on Python View）。这里标记为活跃的环境不是你的 .venv。如果你更习惯旧行为，可以在设置里加 "python.useEnvironmentsExtension": false 退出，重启后选择会回到状态栏。
开始之前
- 先确认 venv 自己是好的：从普通终端
source .venv/bin/activate && python -c "import fastapi"能成功。 - 记下 venv 位置和创建工具（裸
venv、virtualenv、poetry、pdm、uv、conda）。 - 记下 Cursor 状态栏右下角”Python”显示的当前解释器。
- 改之前先保存一份
.vscode/settings.json。
需要收集的信息
- Cursor 集成终端中的
which python与python --version输出。 - Poetry 用户：
poetry env info --path。uv 用户：uv run python -c "import sys; print(sys.executable)"（没有uv venv --path这个子命令）。 .vscode/settings.json中所有 Python 相关键。- 状态栏解释器的完整路径（不是仅看标签）。
- Python 面板里的活跃环境（它可能和状态栏不一致）。
- Pylance “Show language server output” 日志里的
Selected interpreter:行。 - Cursor 是从 Finder、终端
cursor .、还是 Spotlight 启动的。
分步修复
按从快到彻底排序。
第 1 步：通过命令面板显式指定解释器
Cmd+Shift+P -> Python: Select Interpreter -> “Enter interpreter path…”，粘贴绝对路径：
/Users/you/proj/.venv/bin/pythonWindows 上二进制是 .venv\Scripts\python.exe，不是 bin/python。这会把选择写进 workspace 并重启分析器。大约 80% 的情况到这里就解决了。
如果你想用的路径不在列表里，点 “Enter interpreter path…” -> “Find…” 浏览过去。
如果粘贴 .venv/bin/python 报 An invalid Python interpreter is selected，试试让 “Find…” 指向 .venv 文件夹本身，而不是里面的二进制。这是 Cursor 的一个已知怪癖：文件夹能解析，显式的二进制路径反而不行。
如果选完之后 import 还红，先运行 Python: Restart Language Server 再下结论。Pylance 不一定会自己重新加载分析。
第 2 步：在 workspace 设置里把解释器固定下来
打开 .vscode/settings.json 锁死：
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.terminal.activateEnvironment": true,
"python.analysis.extraPaths": ["${workspaceFolder}/src"]
}用 ${workspaceFolder} 让路径在不同机器都通用。提交这个文件，队友也能继承同样的选择。
第 3 步：修好 GUI 启动时的 PATH 继承
如果集成终端里 echo $PATH 缺东西，说明 rc 文件没加载。两种办法。
把设置 PATH 的命令从 .zshrc（仅交互式）挪到 .zprofile（登录 shell，也是 Cursor 终端用的）：
# ~/.zprofile
export PATH="/opt/homebrew/bin:$HOME/.local/bin:$PATH"或者从终端启动 Cursor，让它继承正确的环境：
cursor .两种做法之后都需要把 Cursor 完全退出再启动（不是 Reload Window）。
第 4 步：Poetry / uv / PDM 用户，把 Cursor 指向托管的 venv
Poetry 用户先拿路径，再用第 1 步选中：
poetry env info --path更干净的做法是让 Poetry 把 venv 建在项目内，这样不用固定路径就能自动发现：
poetry config virtualenvs.in-project true
poetry env remove --all
poetry install之后项目根下出现 .venv。
uv 用户在 uv sync（或 uv venv）之后，环境已经在 ./.venv，通常能自动发现。没有 uv venv --path 这个子命令；要确认 uv 用的是哪个解释器，运行：
uv run python -c "import sys; print(sys.executable)"如果你只修好了编辑器，agent 却还在给已装好的包建议 pip install，那是因为 agent 开的是一个全新 shell，不会继承你激活的 venv。在 .cursor/rules 里加一条，让它通过环境跑 Python，例如”在本项目里始终用 uv run 跑 Python 和测试”（或 poetry run）。解释器固定修好的是 Pylance，规则修好的是 agent 在终端里跑的命令。
第 5 步：Conda 用户，装 Anaconda Python 扩展并设置 conda 路径
在 Cursor 扩展里装 “Python”（Microsoft），确认 Conda 集成已启用。然后：
{
"python.condaPath": "/opt/homebrew/Caskroom/miniforge/base/condabin/conda",
"python.defaultInterpreterPath": "/opt/homebrew/Caskroom/miniforge/base/envs/myproj/bin/python"
}通过 Cmd+Shift+P -> Python: Select Interpreter 显式选择 conda 环境。
第 6 步：multi-root workspace，每个根分别固定
multi-root workspace 里，每个文件夹都可以有自己的 .vscode/settings.json。给每个 Python 文件夹都加上：
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}这样在文件之间切换就不会再换解释器。
第 7 步：对齐 Python Environments 面板
如果状态栏显示 .venv、重启后 import 仍红，可能是 Python Environments 扩展里活跃环境不一样。打开 Python 面板（活动栏，或 Cmd+Shift+P -> Python: Focus on Python View），找到你的 .venv，在这里把它设为该 workspace 的活跃环境。如果你更想保留 2026 年之前的状态栏工作流，就退出并重启：
{
"python.useEnvironmentsExtension": false
}验证
- 打开项目里的
.py文件，状态栏显示Python 3.x.x (.venv)或工具名。 - 输入一个只在 venv 里有的包：
import <pkg>，没有红线。 - 在调试会话里跑
python -c "import sys; print(sys.executable)"，输出匹配.venv/bin/python。 - 让 Composer “加一个 fastapi route”，如果包已经在
requirements.txt里，它不应再建议pip install fastapi。
长期预防
- 第一次用 Cursor 打开项目之前，先把 venv 建好。
- 把
python.defaultInterpreterPath写进.vscode/settings.json并提交。 - 用
poetry config virtualenvs.in-project true（或uv sync，它会创建./.venv），让 venv 落在./.venv，能被自动发现。 - PATH 设置写到
.zprofile，不要写在.zshrc，这样 GUI 启动也能继承。 - 在
.cursor/rules里加一条，让 agent 通过环境跑 Python（uv run/poetry run），这样 agent 在终端里的命令和编辑器解释器一致。 - 提供
make setup/just setup之类的命令，新同事 setup 后 venv 就在标准位置。 - 在
pytest启动时import sys; print(sys.prefix)，CI 里 assert 等于.venv。
常见误区
- 选好解释器后又
rm -rf .venv && python -m venv .venv，缓存指向已经不存在的二进制。重新选一次。 - 把
python.defaultInterpreterPath写在 user 设置而不是 workspace 设置：会跨项目泄漏。 - 在集成终端
source .venv/bin/activate然后以为 Pylance 也跟着看见了。Pylance 看的是配置里的解释器，不是终端活跃 venv。 - 只信状态栏标签——它可能写
.venv但实际指向旧路径。一定要用python -c "import sys; print(sys.executable)"验证。 - 从一个 venv 已激活的终端跑
cursor .，行为和从 Finder 启动的不一样。每台机器统一一种启动方式。 - 忘了 conda 环境除了解释器固定，还需要
python.condaPath。
常见问题
Q：Composer / agent 一直建议 pip install 已经装好的包。
分两层。Pylance 和内联分析读的是你选中的解释器，所以修好解释器固定就能消掉红线。但 agent 在一个全新 shell 里跑终端命令，不继承你激活的 venv，所以它仍可能看不到已装的包。在 .cursor/rules 里加一条，让它通过环境跑 Python（uv run、poetry run，或显式的 .venv 路径）。也可参考Cursor 读错文件。
Q：状态栏显示 .venv，但 import 还是红的。
自 Python Environments 扩展于 2026 年 2 月正式发布（GA），状态栏和新的 Python 面板可能不一致。打开面板（Python: Focus on Python View）把 .venv 设为活跃，或设置 "python.useEnvironmentsExtension": false 后重启。
Q：改了 python.defaultInterpreterPath 但没刷新。
Pylance 会缓存分析器状态。Cmd+Shift+P -> Python: Restart Language Server，或者直接 Reload Window。
Q：我的 venv 在 ~/.virtualenvs/myproj，能继续保留吗？
可以——在 .vscode/settings.json 里固定绝对路径即可。但每个项目用 ./.venv 更简单也更可移植。
Q：终端里测试能过，Cursor 测试浏览器里却挂了。
测试运行器用的是 Cursor 配置里的解释器，不是你终端中的活跃 venv。检查二者是否一致。