尝试以扩展 VS Code 中的代理模式!

VS Code 中的 Python 环境

Python 中的“环境”是运行 Python 程序时的上下文,它由一个解释器和任意数量的已安装包组成。

注意:如果你想更熟悉 Python 编程语言,请查阅更多 Python 资源

Python 环境的类型

全局环境

默认情况下,任何已安装的 Python 解释器都在其自己的**全局环境**中运行。例如,如果你在一个新的终端中运行 pythonpython3py(取决于你如何安装 Python),你就是在该解释器的全局环境中运行。你安装或卸载的任何包都会影响全局环境以及你在其中运行的所有程序。

提示:在 Python 中,最佳实践是创建一个特定于工作区的环境,例如,通过使用本地环境。

本地环境

你可以为你的工作区创建两种类型的环境:**虚拟**环境和 **conda** 环境。这些环境允许你安装包而不会影响其他环境,从而隔离了你工作区的包安装。

虚拟环境

一个虚拟环境是一种创建环境的内置方式。虚拟环境会创建一个文件夹,其中包含特定解释器的副本(或符号链接)。当你将包安装到虚拟环境中时,它会最终进入这个新文件夹,从而与其他工作区使用的其他包隔离开来。

注意:虽然可以将虚拟环境文件夹作为工作区打开,但不建议这样做,这可能会导致使用 Python 扩展时出现问题。

Conda 环境

conda 环境是使用 conda 包管理器管理的 Python 环境(请参阅 conda 入门)。在 conda 和虚拟环境之间进行选择取决于你的打包需求、团队标准等。

Python 环境工具

下表列出了与 Python 环境相关的各种工具

工具 定义和用途
pip Python 包管理器,用于安装和更新包。它默认随 Python 3.9+ 一起安装(除非你在基于 Debian 的操作系统上;在这种情况下请安装 python3-pip)。
venv 允许你为不同项目管理独立的包安装,默认随 Python 3 一起安装(除非你在基于 Debian 的操作系统上;在这种情况下请安装 python3-venv)。
conda Miniconda 一起安装。它可用于管理包和虚拟环境。通常用于数据科学项目。

创建环境

使用“创建环境”命令

要在 VS Code 中使用虚拟环境或 Anaconda 创建本地环境,你可以按照以下步骤操作:打开命令面板(⇧⌘P (Windows, Linux Ctrl+Shift+P)),搜索 **Python: Create Environment** 命令,然后选择它。

该命令会列出环境类型:VenvConda

Create Environment dropdown

如果你正在使用 Venv 创建环境,该命令会列出可用作新虚拟环境基础的解释器。

Virtual environment interpreter selection

如果你正在使用 Conda 创建环境,该命令会列出可用于你项目的 Python 版本。

Conda environment Python version selection

选择所需的解释器或 Python 版本后,一个通知将显示环境创建的进度,并且环境文件夹将出现在你的工作区中。

Create environment status notification

注意:该命令还将安装项目文件夹中 requirements.txtpyproject.tomlenvironment.yml 等需求/依赖文件中列出的必要包。它还会在虚拟环境中添加一个 .gitignore 文件,以帮助你避免意外地将虚拟环境提交到源代码控制中。

在终端中创建虚拟环境

如果你选择手动创建虚拟环境,请使用以下命令(其中“.venv”是环境文件夹的名称)

# macOS/Linux
# You may need to run `sudo apt-get install python3-venv` first on Debian-based OSs
python3 -m venv .venv

# Windows
# You can also use `py -3 -m venv .venv`
python -m venv .venv

注意:要了解有关 venv 模块的更多信息,请阅读 Python.org 上的创建虚拟环境

当你创建一个新的虚拟环境时,VS Code 中会显示一个提示,允许你为工作区选择它。

Python environment prompt

提示:请确保更新你的源代码控制设置,以防止意外提交你的虚拟环境(例如在 .gitignore 中)。由于虚拟环境不可移植,将其提交给他人使用通常没有意义。

在终端中创建 conda 环境

Python 扩展会自动检测现有的 conda 环境。我们建议你在 conda 环境中安装一个 Python 解释器,否则在你选择环境后会自动为你安装一个。例如,以下命令创建一个名为 env-01 的 conda 环境,其中包含 Python 3.9 解释器和几个库

conda create -n env-01 python=3.9 scipy=0.15.0 numpy

注意:有关 conda 命令行的更多信息,你可以阅读 Conda 环境

附加说明

  • 如果在 VS Code 运行时创建了一个新的 conda 环境,请使用 **Python: Select Interpreter** 窗口右上角的刷新图标;否则你可能在那里找不到该环境。

    Conda environment refresh icon

  • 为了确保从 shell 的角度正确设置环境,请使用 Anaconda 提示符并激活所需的环境。然后,你可以通过输入 code . 命令启动 VS Code。一旦 VS Code 打开,你可以使用命令面板或点击状态栏来选择解释器。

  • 虽然 VS Code 的 Python 扩展目前没有与 conda environment.yml 文件直接集成,但 VS Code 本身是一个很好的 YAML 编辑器。

  • 如果默认 shell 设置为 PowerShell,则无法在 VS Code 集成终端中自动激活 Conda 环境。要更改 shell,请参阅集成终端 - 终端配置文件

  • 你可以手动指定用于激活的 conda 可执行文件的路径(版本 4.4+)。为此,请打开命令面板(⇧⌘P (Windows, Linux Ctrl+Shift+P))并运行 **Preferences: Open User Settings**。然后在用户设置的 Python 扩展部分设置 python.condaPath,并填入适当的路径。

使用 Python 解释器

选择并激活一个环境

Python 扩展会尝试查找并选择它认为最适合工作区的环境。如果你希望选择一个特定的环境,请从**命令面板**(⇧⌘P (Windows, Linux Ctrl+Shift+P))使用 **Python: Select Interpreter** 命令。

Python: Select Interpreter command

注意:如果 Python 扩展找不到解释器,它会发出警告。在 macOS 12.2 及更早版本上,如果你使用的是操作系统安装的 Python 解释器,扩展也会发出警告,因为已知它存在兼容性问题。在任何一种情况下,你都可以通过在用户设置中将 python.disableInstallationCheck 设置为 true 来禁用这些警告。

Python: Select Interpreter 命令会显示一个包含可用全局环境、conda 环境和虚拟环境的列表。(有关详细信息,包括这些环境类型之间的区别,请参阅扩展在哪里查找环境部分。)例如,下图显示了几个 Anaconda 和 CPython 安装,以及一个 conda 环境和一个位于工作区文件夹内的虚拟环境(env

List of interpreters

注意:在 Windows 上,VS Code 检测可用的 conda 环境可能需要一些时间。在此过程中,你可能会在环境路径前看到“(cached)”。该标签表示 VS Code 当前正在使用该环境的缓存信息。

如果你在 VS Code 中打开了一个文件夹或工作区,并从列表中选择了一个解释器,Python 扩展将在内部存储该信息。这确保了当你重新打开工作区时,将使用相同的解释器。

选定的环境被 Python 扩展用于运行 Python 代码(使用 **Python: Run Python File in Terminal** 命令),在你打开一个 .py 文件时提供语言服务(自动完成、语法检查、代码检查、格式化等),以及使用 **Terminal: Create New Terminal** 命令打开一个终端。在后一种情况下,VS Code 会自动激活选定的环境。

提示:要阻止自动激活选定的环境,请将 "python.terminal.activateEnvironment": false 添加到你的 settings.json 文件中(它可以放在现有设置的任何位置作为同级项)。

提示:如果激活命令生成消息“Activate.ps1 未进行数字签名。您不能在当前系统上运行此脚本。”,那么您需要临时更改 PowerShell 执行策略以允许脚本运行(请参阅 PowerShell 文档中的关于执行策略):Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

注意:默认情况下,VS Code 在调试代码时使用为你的工作区选择的解释器。你可以通过在调试配置的 python 属性中指定不同的路径来覆盖此行为。请参阅选择调试环境

所选解释器版本将显示在状态栏的右侧。

Status Bar showing a selected interpreter

状态栏也会反映未选择解释器的情况。

Status bar showing no selected Python interpreter

在任何一种情况下,点击状态栏的这个区域都是 **Python: Select Interpreter** 命令的便捷快捷方式。

提示:如果你在 VS Code 识别虚拟环境时遇到任何问题,请提交一个问题,以便我们帮助确定原因。

手动指定解释器

如果 VS Code 没有自动定位到你想使用的解释器,你可以在文件系统中浏览解释器或手动提供其路径。

你可以通过运行 **Python: Select Interpreter** 命令并选择解释器列表顶部的 **Enter interpreter path...** 选项来做到这一点。

Enter interpreter path option on the interpreters list

然后,你可以直接在文本框中输入 Python 解释器的完整路径(例如,“.venv/Scripts/python.exe”),或者你可以选择 **Find...** 按钮并浏览你的文件系统以找到你希望选择的 python 可执行文件。

Enter path or browse for an interpreter

如果你想手动指定一个默认解释器,以便在首次打开工作区时使用,你可以为 python.defaultInterpreterPath 设置创建或修改一个条目。

注意:在为工作区选择了某个解释器之后,对 python.defaultInterpreterPath 设置的更改将不会被采纳;一旦为工作区选择了初始解释器,对该设置的任何更改都将被忽略。

此外,如果你想为所有 Python 应用程序设置一个默认解释器,你可以在你的用户设置中手动添加一个 python.defaultInterpreterPath 条目。为此,请打开命令面板(⇧⌘P (Windows, Linux Ctrl+Shift+P))并输入 **Preferences: Open User Settings**。然后在用户设置的 Python 扩展部分设置 python.defaultInterpreterPath,并填入相应的解释器。

扩展如何自动选择环境

如果尚未指定解释器,则 Python 扩展会按以下优先级顺序自动选择版本最高的解释器

  1. 直接位于工作区文件夹下的虚拟环境。
  2. 与工作区相关但全局存储的虚拟环境。例如,位于工作区文件夹之外的 PipenvPoetry 环境。
  3. 全局安装的解释器。例如,在 /usr/local/binC:\\python38 等处找到的解释器。

注意:所选的解释器可能与您终端中的 python 所指向的不同。

如果 Visual Studio Code 没有自动定位到您的解释器,您可以手动指定一个解释器

扩展在哪里查找环境

扩展会自动在以下位置查找解释器,顺序不分先后

  • 标准安装路径,如 /usr/local/bin/usr/sbin/sbinc:\\python36 等。
  • 直接位于工作区(项目)文件夹下的虚拟环境。
  • 位于 python.venvPath 设置所标识文件夹中的虚拟环境(请参阅通用 Python 设置),该文件夹可以包含多个虚拟环境。扩展在 venvPath 的第一级子文件夹中查找虚拟环境。
  • 位于 ~/.virtualenvs 文件夹中的用于 virtualenvwrapper 的虚拟环境。
  • pyenvPipenvPoetry 创建的解释器。
  • 位于 WORKON_HOME(由 virtualenvwrapper 使用)所标识路径中的虚拟环境。
  • 通过 conda env list 找到的 Conda 环境。没有解释器的 Conda 环境在选择后将为其安装一个。
  • 在工作区文件夹下为 direnv 安装在 .direnv 文件夹中的解释器。

环境和终端窗口

使用 **Python: Select Interpreter** 后,当右键单击文件并选择 **Python: Run Python File in Terminal** 时,将应用该解释器。当您使用 **Terminal: Create New Terminal** 命令时,该环境也会自动激活,除非您将 python.terminal.activateEnvironment 设置更改为 false

请注意,从已激活特定 Python 环境的 shell 启动 VS Code 不会自动在默认的集成终端中激活该环境。

注意:如果 PowerShell 被设置为集成 shell,conda 环境无法在集成终端中自动激活。有关如何更改 shell,请参阅集成终端 - 终端配置文件

使用 **Python: Select Interpreter** 命令更改解释器不会影响已经打开的终端面板。因此,你可以在一个拆分的终端中激活不同的环境:选择第一个解释器,为它创建一个终端,选择一个不同的解释器,然后使用终端标题栏中的拆分按钮(⌘\ (Windows, Linux Ctrl+Shift+5))。

选择一个调试环境

默认情况下,调试器将使用通过 Python 扩展选择的 Python 解释器。但是,如果 launch.json 的调试配置中指定了 python 属性,它将优先。如果未定义此属性,它将回退到使用为工作区选择的 Python 解释器路径。

有关调试配置的更多详细信息,请参阅调试配置

环境变量

环境变量定义文件

环境变量定义文件是一个包含键值对的文本文件,格式为 environment_variable=value,使用 # 表示注释。不支持多行值,但允许引用先前定义的环境变量。环境变量定义文件可用于调试和工具执行(包括 linter、formatter、IntelliSense 和测试工具)等场景,但不适用于终端。

注意:环境变量定义文件不一定是跨平台的。例如,Unix 在环境变量中使用 : 作为路径分隔符,而 Windows 使用 ;。没有对这种操作系统差异进行标准化,因此你需要确保任何环境定义文件都使用与你的操作系统兼容的值。

默认情况下,Python 扩展会查找并加载当前工作区文件夹中名为 .env 的文件,然后应用这些定义。该文件由您用户设置中的默认条目 "python.envFile": "${workspaceFolder}/.env" 标识(请参阅通用 Python 设置)。您可以随时更改 python.envFile 设置以使用不同的定义文件。

注意:环境变量定义文件并非在所有可以使用环境变量的情况下都使用。除非 Visual Studio Code 文档另有说明,否则根据其定义,这些文件仅影响某些特定场景。例如,扩展在解析设置值时不会使用环境变量定义文件。

调试配置还包含一个 envFile 属性,该属性也默认为当前工作区中的 .env 文件(请参阅调试 - 设置配置选项)。此属性允许您轻松地为调试目的设置变量,这些变量将替换默认 .env 文件中指定的变量。

例如,在开发 Web 应用程序时,您可能希望轻松地在开发服务器和生产服务器之间切换。您可以为每个服务器使用单独的定义文件,而不是将不同的 URL 和其他设置直接编码到您的应用程序中。例如

dev.env 文件

# dev.env - development configuration

# API endpoint
MYPROJECT_APIENDPOINT=https://my.domain.com/api/dev/

# Variables for the database
MYPROJECT_DBURL=https://my.domain.com/db/dev
MYPROJECT_DBUSER=devadmin
MYPROJECT_DBPASSWORD=!dfka**213=

prod.env 文件

# prod.env - production configuration

# API endpoint
MYPROJECT_APIENDPOINT=https://my.domain.com/api/

# Variables for the database
MYPROJECT_DBURL=https://my.domain.com/db/
MYPROJECT_DBUSER=coreuser
MYPROJECT_DBPASSWORD=kKKfa98*11@

然后,你可以将 python.envFile 设置为 ${workspaceFolder}/prod.env,再将调试配置中的 envFile 属性设置为 ${workspaceFolder}/dev.env

注意:当使用多种方法指定环境变量时,请注意存在一个优先级顺序。在 launch.json 文件中定义的所有 env 变量将覆盖由 python.envFile 设置(用户或工作区)指定的 .env 文件中包含的变量。同样,在 launch.json 文件中定义的 env 变量将覆盖在 launch.json 中指定的 envFile 中定义的环境变量。

PYTHONPATH 变量的使用

PYTHONPATH 环境变量指定了 Python 解释器应查找模块的其他位置。在 VS Code 中,可以通过终端设置 (terminal.integrated.env.*) 和/或在 .env 文件中设置 PYTHONPATH。

当使用终端设置时,PYTHONPATH 会影响用户在终端内运行的任何工具,以及扩展为用户执行的、通过终端路由的任何操作,例如调试。但是,在这种情况下,当扩展执行未通过终端路由的操作时,例如使用 linter 或 formatter,则此设置不会对模块查找产生影响。

后续步骤

  • 编辑代码 - 了解 Python 的自动完成、IntelliSense、格式设置和重构。
  • 调试 - 了解如何在本地和远程调试 Python。
  • 测试 - 配置测试环境以及发现、运行和调试测试。
  • 设置参考 - 探索 VS Code 中所有与 Python 相关的设置。

更多 Python 资源