VS Code 中的 Python 环境

Python Environments 扩展将环境和包管理功能引入了 Visual Studio Code 的用户界面。无论您使用的是 venv、uv、conda、pyenv、poetry 还是 pipenv，该扩展都提供了一个统一的界面来创建环境、安装包和切换解释器。

核心功能

• 创建、删除和在环境之间切换
• 安装和管理包
• 终端中的激活 Python 环境
• 将环境分配给特定文件或文件夹（称为“Python 项目”）

该扩展与 Python 扩展协同工作，无需任何设置即可开始使用。

快速入门

大多数用户无需进行任何配置。扩展会自动发现您的 Python 环境并在运行代码时使用它们。

如果您使用基础设置（例如，整个工作区使用一个环境）：

1. 打开一个 Python 文件
2. 检查状态栏以查看当前激活的环境
3. 要切换环境，请选择状态栏中的环境控件

需要创建环境？打开 Python 侧边栏，展开 Environment Managers（环境管理器），然后选择 + 按钮。扩展将引导您完成不同的步骤。

用户界面组件

环境发现

以下环境管理器会被自动发现：

扩展激活时会自动运行发现过程。扩展使用 Python Environment Tool (PET) Rust 二进制文件来扫描您系统中的 Python 环境。PET 通过检查 PATH（例如查找 conda、pyenv 和 poetry 可执行文件）和已知安装位置来查找环境管理器，然后搜索由这些环境管理器管理的环境。

手动触发刷新：

1. 打开命令面板 (Cmd+Shift+P 或 Ctrl+Shift+P)
2. 运行 Python Environments: Refresh All Environment Managers

您也可以点击 Environment Managers 视图标题中的刷新图标。

选择刷新图标以重新扫描环境。

查看已发现的环境

已发现的环境出现在两个位置：

• Environment Managers 视图：在 Python 侧边栏中，环境按管理器类型分组（例如 venv、Conda 等）
• 环境选择器：为项目选择解释器时，所有已发现的环境都会出现在一个统一的列表中

Environment Managers 视图按类型对环境进行分组。

配置搜索路径

默认情况下，扩展会使用 glob 模式 ./**/.venv 在您的整个工作区中搜索虚拟环境。这会找到工作区中任何位置名为 .venv 的文件夹。

要在自定义位置发现环境，请更新 python-envs.workspaceSearchPaths 设置。

{
  "python-envs.workspaceSearchPaths": ["./**/.venv", "./envs/**", "./my-custom-env"]
}

提示:

• 使用 ** 进行递归搜索（例如，./**/env 会找到任何深度下名为 env 的文件夹）
• 相对路径是相对于工作区文件夹根目录解析的

快速打开搜索路径设置：

1. 打开命令面板
2. 运行 Python Environments: Configure Search Settings

添加自定义 glob 模式以搜索其他位置。

全局搜索路径：对于工作区外部的环境（如共享的 ~/envs 文件夹），请使用 python-envs.globalSearchPaths。

{
  "python-envs.globalSearchPaths": ["/Users/yourname/envs", "/opt/shared-envs"]
}

此设置需要绝对路径，并配置在用户（全局）级别。

旧版设置：如果您之前使用过 python.venvPath 或 python.venvFolders，这些设置会自动合并到新的搜索路径中。建议迁移到 python-envs.globalSearchPaths 以保持未来的兼容性。

选择环境

要使用已发现的环境：

• 状态栏：选择窗口底部显示的 Python 版本
• 命令面板：运行 Python: Select Interpreter 并从列表中进行选择

选定的环境将用于运行代码、调试以及 IntelliSense 等语言功能。

选择状态栏中的 Python 版本以切换环境。 扩展如何自动选择：当您打开一个工作区而未明确选择环境时，扩展会按以下顺序自动选择：

1. 工作区本地虚拟环境 (.venv, venv)
2. 全局/系统解释器

要覆盖此优先级顺序，请将 python-envs.defaultEnvManager 设置为首选特定管理器（例如 ms-python.python:conda），或配置 Python 项目以实现按文件夹控制。旧版设置仍然受到支持。

排查环境发现问题

对于高级故障排查，直接运行 Python Environment Tool (PET) 以查看原始发现输出：

1. 打开命令面板
2. 运行 Python Environments: Run Python Environment Tool (PET) in Terminal...
3. 选择一个选项：
   • Find All Environments：运行 pet find --verbose 以列表形式输出所有发现的环境及详细信息
   • Resolve Environment...：输入 Python 可执行文件的路径，以调试特定环境为何未被检测到

PET 的详细输出会明确显示发现了哪些环境及其原因。

高级故障排查适用于以下场景：

• 您需要验证环境是否被检测到
• 您想了解环境为何出现在特定管理器下
• 您正在调试路径解析问题

创建、删除和管理环境

创建环境

扩展提供了两种创建环境的方法：快速创建 (Quick Create) 以追求速度，自定义创建 (Custom Create) 以实现精细控制。

快速创建

在 Environment Managers 视图中选择 + 按钮。扩展将执行以下步骤：

• 使用您的默认管理器（默认为 venv，可通过 python-envs.defaultEnvManager 配置）
• 选择可用的最新 Python 版本
• 将环境命名为 .venv（如果已存在，则为 .venv-1、.venv-2 等）
• 如果找到 requirements.txt 或 pyproject.toml，则安装依赖项
• 为您的工作区选择新创建的环境

这是获取工作环境的最快方法。

快速创建会构建一个具有合理默认值的环境。

自定义创建

如需更多控制权，请在命令面板中运行 Python: Create Environment 并按照提示操作：

1. 选择管理器：venv 或 conda
2. 选择 Python 版本：从已发现的解释器（venv）或可用的 Python 版本（conda）中进行选择
3. 命名环境：输入自定义名称或接受默认名称
4. 安装依赖项：选择从 requirements.txt、pyproject.toml 或 environment.yml 安装

自定义创建允许您配置每一个步骤。

使用 uv 加快创建速度

如果安装了 uv，扩展会自动将其用于 venv 创建和包安装，这比标准工具要快得多。通过以下方式配置：

{
  "python-envs.alwaysUseUv": true
}

启用 alwaysUseUv（默认设置）时，uv 会管理所有虚拟环境。将其设为 false 则仅对明确由 uv 创建的环境使用 uv。

支持的管理器

删除环境

要删除环境：

1. 在 Environment Managers 视图中，找到该环境
2. 右键点击并选择 Delete（删除）

删除环境会从磁盘中移除环境文件夹。任何使用此环境的项目都将需要您重新选择一个环境。

Python 项目

Python 项目是指您希望与特定环境关联的任何文件或文件夹。默认情况下，您的整个工作区使用一个环境。项目允许您为不同的文件夹分配不同的环境。这对于单体仓库 (mono-repos)、微服务或跨 Python 版本测试至关重要。

为什么要使用项目？

如果您整个工作区只有一个环境，则无需显式设置项目。选择一个解释器即可。

Workspace
├── Python Project: backend/
│     └── Environment: .venv (Python 3.12)
│            └── Manager: venv
│
├── Python Project: frontend-utils/
│     └── Environment: .venv (Python 3.10)
│            └── Manager: venv
│
└── Python Project: ml-pipeline/
       └── Environment: ml-env (Python 3.11)
              └── Manager: conda

哪些功能使用项目分配？

• 运行和调试：使用该项目的环境
• 终端：使用该项目的环境激活
• 测试资源管理器：每个项目都有自己的测试树及其自己的解释器（参见 多项目测试）

添加项目

要将文件夹或文件视为单独的项目：

1. 在资源管理器中右键点击它
2. 选择 Add as Python Project

或者，在 Python Projects 视图中选择 +，并选择以下选项之一：

• Add Existing：手动选择文件/文件夹
• Auto Find：发现带有 pyproject.toml 或 setup.py 的文件夹

添加现有文件夹或自动发现项目。

分配环境

将文件夹设为项目后，即可分配其环境：

1. 在 Python Projects 视图中，点击您项目下显示的环境（或“No environment”）
2. 从已发现的环境中进行选择

选定的环境将在您在该项目中运行或调试文件时使用。

点击环境以更改它。

设置如何存储

当您将环境分配给项目时，扩展会写入您的工作区设置 (.vscode/settings.json)。

{
  "python-envs.pythonProjects": [
    {
      "path": "backend",
      "envManager": "ms-python.python:venv"
    },
    {
      "path": "ml-service",
      "envManager": "ms-python.python:conda"
    }
  ]
}

请注意，设置存储的是环境管理器，而不是硬编码的解释器路径。扩展会分别记录您选择的特定环境，并在运行时解析它。这种设计使设置具有可共享性：

• 无机器特定路径：队友不需要 /Users/yourname/.venv
• 跨系统可移植：适用于 macOS、Windows 和 Linux
• 环境重建后依然有效：如果您删除并重新创建 .venv，它仍可工作

与队友共享

1. 将 .vscode/settings.json 提交到您的仓库
2. 队友克隆并打开工作区
3. 他们创建自己的环境（此处“快速创建”非常好用）
4. 扩展自动使用每个项目配置的管理器

删除项目

在 Python Projects 视图中右键点击项目并选择 Remove Python Project。这会删除映射。它不会删除任何文件。

从模板创建项目

要使用正确的结构脚手架一个新项目，请从命令面板运行 Python Envs: Create New Project from Template。选择：

• Package：创建一个包含 pyproject.toml、包目录和测试的文件夹
• Script：创建一个带有内联依赖元数据 (PEP 723) 的单个 .py 文件

有关模板结构的详细信息，请参阅完整的 Python 项目指南。

了解更多

有关模板、多根工作区、常见场景和故障排查的详细指导，请参阅完整的 Python 项目指南。

包管理

直接从 VS Code 安装和卸载 Python 包，无需打开终端。

安装包

1. 在 Environment Managers 视图中，找到一个环境
2. 右键点击并选择 Manage Packages
3. 搜索包并选择您想要安装的包

或者从命令面板运行 Python Envs: Manage Packages。

直接从 VS Code 搜索并安装包。

从需求文件安装：您也可以从 requirements.txt、pyproject.toml 或 environment.yml 安装包。出现提示时，选择该文件，扩展会安装所有列出的依赖项。

卸载包

1. 在 Environment Managers 视图中展开一个环境以查看已安装的包
2. 右键点击一个包并选择 Uninstall Package

按环境划分的包管理器

扩展会根据您的环境自动使用合适的包管理器：

要覆盖默认设置，请设置 python-envs.defaultPackageManager。

使用 uv 加快安装速度

如果安装了 uv 且启用了 python-envs.alwaysUseUv（默认设置），venv 环境中的包安装将使用 uv pip 而不是常规的 pip，这对于大型依赖树来说速度显著提升。

设置与配置

本节涵盖了所有扩展设置、解释器选择的工作原理以及旧版设置迁移。

解释器选择优先级

当您打开工作区时，扩展会通过按顺序检查以下来源来确定使用哪个环境：

核心原则：用户配置的设置总是优于默认设置。如果您尚未明确设置 defaultEnvManager（即它仍是内置的默认值），扩展会跳过它并检查下一个优先级。

缓存：为了提高性能，扩展会缓存已解析的环境，但您的显式设置总是优先于缓存值。您永远不必担心过期的缓存覆盖您的选择。

有关解释器选择行为的更多详细信息，请参阅 解释器选择快速参考。

设置何时写入

仅当您做出显式更改时，扩展才会写入设置：

这确保了打开工作区不会将自动生成的条目添加到您的 settings.json 中。

Python Environments 设置

终端设置

当您在 VS Code 中打开终端时，扩展会自动激活您选择的 Python 环境，以便 python、pip 和相关命令使用正确的解释器。

终端激活类型

为特定环境打开终端

您可以打开一个激活了任何环境的新终端：

1. 在 Environment Managers 视图中，找到该环境
2. 右键点击并选择 Open in Terminal

打开一个已激活任意环境的终端。

有关详细的故障排查及激活原理，请参阅 终端自动激活说明。

.env 文件支持

要将来自 .env 文件的环境变量注入到您的终端：

1. 在您的工作区根目录创建一个 .env 文件或使用 python.envFile 指定自定义路径
2. 将 python.terminal.useEnvFile 设置为 true

# .env
API_KEY=your-secret-key
DATABASE_URL=postgres:///mydb

变量在终端创建时注入。这对于不应提交到源代码控制的开发凭据非常有用。

旧版设置

这些来自 Python 扩展的设置仍然受到支持，但已有更新的替代方案：

设置范围参考

设置根据其配置位置表现不同：

核心洞察：workspaceSearchPaths 必须在工作区或文件夹级别（而非用户级别）设置，因为它是相对于工作区文件夹的。

可扩展性

Python Environments 扩展旨在实现可扩展。任何环境或包管理器都可以构建一个接入 Python 侧边栏的扩展，与内置管理器并列显示。这意味着生态系统无需等待此扩展的更新即可支持新工具。

社区成员正在为其他环境管理器构建扩展，例如 Pixi 扩展。

已知限制

Pylance 和多项目工作区

Pylance 不支持在同一工作区中使用具有不同解释器的多个 Python 项目。即使您使用 Python 项目为不同文件夹配置了单独的环境，Pylance 仍会为整个工作区使用单个解释器——通常是与工作区根目录关联的那个。要为不同文件夹使用不同的解释器，请将它们添加为 多根工作区 中的工作区文件夹（文件 > 将文件夹添加到工作区），因为 Pylance 是按工作区文件夹独立运行的。

Jupyter 笔记本

Jupyter 笔记本不使用 Python Environments API 进行环境发现。相反，它们依赖于旧的 Python 扩展 API。这意味着笔记本内核选择器显示的可能与 Environment Managers 视图中的环境集不同。

后续步骤

• Python 教程 - 开始在 VS Code 中使用 Python。
• 调试 - 学习调试您的 Python 代码。
• 测试 - 为您的 Python 项目配置并运行测试。
• 设置参考 - 探索所有 Python 扩展设置。