Visual Studio Code

VS Code 中的 Python 环境

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

注意: 如果您想更熟悉Python编程语言，请查看更多Python资源。

Python环境的类型

全局环境

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

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

本地环境

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

虚拟环境

一个虚拟环境是一种内置的创建环境的方式。虚拟环境会创建一个文件夹，其中包含特定解释器的副本（或符号链接）。当你在虚拟环境中安装包时，这些包会被安装到这个新文件夹中，从而与其他工作空间使用的包隔离。

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

Conda 环境

一个conda环境是一个使用conda包管理器管理的Python环境（参见开始使用conda）。在conda和虚拟环境之间选择取决于您的打包需求、团队标准等。

Python 环境工具

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

Tool Definition and Purpose
pip The Python package manager that installs and updates packages. It's installed with Python 3.9+ by default (unless you are on a Debian-based OS; install python3-pip in that case).
venv Allows you to manage separate package installations for different projects and is installed with Python 3 by default (unless you are on a Debian-based OS; install python3-venv in that case)
conda Installed with Miniconda. It can be used to manage both packages and virtual environments. Generally used for data science projects.

创建环境

使用创建环境命令

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

该命令显示了一个环境类型列表：Venv 或 Conda。

创建环境下拉菜单

如果您正在使用Venv创建环境，该命令会显示一个解释器列表，这些解释器可以用作新虚拟环境的基础。

虚拟环境解释器选择

如果您正在使用Conda创建环境，该命令会显示一个可用于您项目的Python版本列表。

Conda环境Python版本选择

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

创建环境状态通知

注意: 该命令还将安装项目文件夹中列出的必要包，如requirements.txt、pyproject.toml或environment.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环境提示

提示: 确保更新您的源代码控制设置，以防止意外提交您的虚拟环境（例如在.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: 选择解释器窗口右上角的刷新图标；否则您可能无法在那里找到该环境。

    Conda环境刷新图标

  • 为了确保从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））并运行首选项：打开用户设置。然后在用户设置的Python扩展部分中设置python.condaPath，并填写适当的路径。

使用 Python 解释器

选择并激活环境

Python 扩展会尝试找到并选择它认为最适合工作区的环境。如果您更倾向于选择特定的环境，请使用 命令面板 中的 Python: 选择解释器 命令（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。

Python: 选择解释器命令

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

Python: 选择解释器 命令显示可用的全局环境、conda环境和虚拟环境的列表。（详情请参见扩展查找环境的位置部分，包括这些类型环境之间的区别。）例如，下图显示了几个Anaconda和CPython安装，以及一个conda环境和一个位于工作区文件夹内的虚拟环境（env）：

解释器列表

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

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

所选环境由Python扩展用于运行Python代码（使用Python: 在终端中运行Python文件命令），当你在编辑器中打开.py文件时，提供语言服务（自动完成、语法检查、linting、格式化等），并使用终端: 创建新终端命令打开终端。在后一种情况下，VS Code会自动激活所选环境。

提示: 为了防止自动激活选定的环境，请将 "python.terminal.activateEnvironment": false 添加到您的 settings.json 文件中（它可以作为现有设置的兄弟节点放置在任何位置）。

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

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

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

状态栏显示选中的解释器

当没有选择解释器时，状态栏也会反映出来。

状态栏显示未选择Python解释器

无论哪种情况，点击状态栏的这个区域都是Python: Select Interpreter命令的便捷快捷方式。

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

手动指定解释器

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

你可以通过运行Python: 选择解释器命令并选择显示在解释器列表顶部的输入解释器路径...选项来实现：

在解释器列表上输入解释器路径选项

然后，您可以直接在文本框中输入Python解释器的完整路径（例如，".venv/Scripts/python.exe"），或者您可以选择查找...按钮并浏览您的文件系统以找到您希望选择的python可执行文件。

输入路径或浏览解释器

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

注意: 对python.defaultInterpreterPath设置的更改在工作空间已经选择了解释器后不会被采纳；一旦为工作空间选择了初始解释器，对该设置的任何更改都将被忽略。

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

扩展如何自动选择环境

如果未指定解释器，则Python扩展程序将按照以下优先级顺序自动选择版本最高的解释器：

  1. 直接位于工作区文件夹下的虚拟环境。
  2. 与工作区相关但全局存储的虚拟环境。例如，位于工作区文件夹之外的Pipenv或Poetry环境。
  3. 全局安装的解释器。例如，在/usr/local/bin、C:\\python38等路径中找到的解释器。

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

如果 Visual Studio Code 没有自动找到您的解释器，您可以手动指定解释器。

扩展在哪里寻找环境

扩展程序会自动在以下位置查找解释器，顺序不限：

  • 标准安装路径，例如 /usr/local/bin, /usr/sbin, /sbin, c:\\python36 等。
  • 直接位于工作空间（项目）文件夹下的虚拟环境。
  • 虚拟环境位于由python.venvPath设置标识的文件夹中（参见通用Python设置），该文件夹可以包含多个虚拟环境。扩展程序会在venvPath的一级子文件夹中查找虚拟环境。
  • 位于~/.virtualenvs文件夹中的虚拟环境，用于virtualenvwrapper。
  • 由pyenv、Pipenv和Poetry创建的解释器。
  • 位于由WORKON_HOME标识的路径中的虚拟环境（由virtualenvwrapper使用）。
  • 通过conda env list找到的Conda环境。没有解释器的Conda环境在选择时会为其安装一个解释器。
  • 在工作空间文件夹下的.direnv文件夹中安装的解释器，用于direnv。

环境和终端窗口

在使用Python: 选择解释器后，当右键点击文件并选择Python: 在终端中运行Python文件时，将应用该解释器。除非你将python.terminal.activateEnvironment设置更改为false，否则在使用终端: 创建新终端命令时，环境也会自动激活。

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

注意： 如果PowerShell被设置为集成终端，conda环境无法在集成终端中自动激活。请参阅集成终端 - 终端配置文件了解如何更改终端。

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

选择调试环境

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

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

环境变量

环境变量定义文件

环境变量定义文件是一个包含键值对的文本文件，格式为environment_variable=value，其中#用于注释。不支持多行值，但允许引用先前定义的环境变量。环境变量定义文件可用于调试和工具执行（包括linters、formatters、IntelliSense和测试工具）等场景，但不适用于终端。

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

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

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

调试配置还包含一个envFile属性，该属性也默认为当前工作空间中的.env文件（参见调试 - 设置配置选项）。此属性允许您轻松设置用于调试的变量，这些变量将替换默认.env文件中指定的变量。

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

开发环境文件

# 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中，PYTHONPATH可以通过终端设置（terminal.integrated.env.*）和/或在.env文件中设置。

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

下一步

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

更多Python资源

12/11/2024