在 VS Code 中创建并激活 Python 虚拟环境管理第三方库

在开发 Python 项目时，直接将第三方库安装到系统全局环境容易引发不同项目之间的版本依赖冲突。在 Visual Studio Code（简称 VS Code）中，为每个项目创建独立的虚拟环境（Virtual Environment）并正确激活，是隔离项目依赖、保持开发环境稳定可控的标准工作流。本文将从底层隔离原理切入，完整演示在 VS Code 中通过界面命令与终端创建、绑定解释器并激活虚拟环境的具体步骤，以及如何规范管理第三方库与排查常见环境异常。

一、核心机制：为什么必须使用虚拟环境

Python 解释器在执行 import 语句时，会按照特定路径顺序查找模块，其中第三方库默认存放在当前解释器安装目录下的 site-packages 文件夹中。如果不使用虚拟环境，所有通过 pip install 安装的库都会堆积在全局 Python 环境中。

当项目 A 需要使用特定旧版本的第三方库（例如 Django 3.2），而项目 B 需要使用更新版本（例如 Django 4.2）时，全局环境将无法同时满足两者的兼容性要求。安装新版本会覆盖旧版本，进而导致早期项目崩溃。此外，在操作系统升级或多人协作时，全局环境中夹杂的大量无关依赖也难以理清。

Python 内置的 venv 模块通过在项目根目录下创建一个专属文件夹（通常命名为 .venv），在其中放置指向宿主 Python 可执行文件的轻量级符号链接或副本，并建立专属的 site-packages 目录。通过这种方式，项目获得了完全独立的运行沙箱。

二、环境准备与前置要求

在开始操作之前，请确保已满足以下基础环境：

1. 已安装 Python 3.8 或更高版本：可在系统终端执行 python3 --version 或 python --version 确认已正确配置环境变量。
2. 已安装 VS Code 官方 Python 扩展：在 VS Code 扩展市场（Extensions，快捷键 Ctrl+Shift+X 或 Cmd+Shift+X）中搜索并安装由 Microsoft 官方维护的 Python 扩展包（包含 Pylance、Debugger 等套件）。
3. 已打开独立的项目工作区目录：在 VS Code 中点击菜单栏 文件 -> 打开文件夹（File -> Open Folder），进入本次项目的专属根目录。不要在没有打开文件夹的单文件模式下配置虚拟环境。

三、在 VS Code 中创建虚拟环境的具体步骤

VS Code 提供了直观的可视化界面操作命令，同时也完全支持在集成终端中使用标准命令创建。以下推荐使用官方集成度最高的图形化命令流程。

方式一：使用 VS Code 内置命令面板创建（推荐）

1. 在已打开的项目窗口中，按下快捷键 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出顶部命令面板。
2. 在输入框中键入 Python: Create Environment（Python: 创建环境），并按回车确认。
3. 选择环境类型：面板中会弹出 Venv 与 Conda 两个选项，点击 Venv。
4. 选择基础解释器：系统会列出已检测到的本机 Python 解释器列表（例如 Python 3.10.x、Python 3.11.x 等），根据需要点击对应版本作为基准。
5. 依赖选择（可选）：若项目中存在 requirements.txt 或 pyproject.toml，VS Code 会提示是否一并安装依赖，勾选或直接按回车跳过。
6. 等待右下角提示框完成操作。VS Code 会在项目根目录下自动创建名为 .venv 的文件夹，并自动将当前工作区的默认解释器指向该虚拟环境。

方式二：通过内置集成终端命令行创建

如果希望更明确地掌控底层创建参数，也可以直接在 VS Code 内置终端中执行 Python 原生命令：

# 打开 VS Code 内置终端（快捷键 Ctrl + ` 或通过菜单 终端 -> 新建终端）
# 在项目根目录下创建名为 .venv 的虚拟环境
python3 -m venv .venv

# Windows 下通常使用 python 或 py 启动器
python -m venv .venv

执行完毕后，左侧资源管理器中将出现 .venv 目录。此时 VS Code 通常会在右下角弹窗询问：“已检测到新的虚拟环境，是否将其选择为当前工作区解释器？”，直接点击 “是”（Yes） 即可完成关联。

四、解释器选择与终端环境激活

创建虚拟环境只是第一步。在 VS Code 中，“代码编辑/调试时使用的 Python 解释器” 与 “集成终端中执行命令的 Shell 环境” 是两个层面的概念，必须确保两者同步生效。

1. 手动核对或切换解释器

如果 VS Code 没有自动识别到 .venv，可以通过以下步骤手动指定：

1. 按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P），输入并选择 Python: Select Interpreter（选择解释器）。
2. 在弹出的列表中，优先选择带有 ('.venv': venv) 标记的项。
3. 如果列表中未显示，可点击 Enter interpreter path...（输入解释器路径），选择 Find...（浏览），并在项目中定位到：
   • Windows 系统：.venv\Scripts\python.exe
   • macOS / Linux 系统：.venv/bin/python

2. 激活虚拟环境并进行验证

绑定解释器后，点击菜单栏 终端 -> 新建终端（Terminal -> New Terminal）。VS Code 会检测到当前工作区已绑定 .venv，并在终端打开时自动调用激活脚本。

验证是否激活成功：

• 观察终端命令行左侧是否出现了带括号的环境名标识，例如 (.venv)。
• 在终端执行路径查询命令，确认返回路径指向当前项目下的 .venv 文件夹，而非全局路径：

# 检查当前 python 路径
which python
# 示例正确输出：/Users/username/my_project/.venv/bin/python

# 检查当前 pip 路径
which pip
# 示例正确输出：/Users/username/my_project/.venv/bin/pip

# 检查当前 python 路径
Get-Command python | Select-Object -ExpandProperty Source
# 示例正确输出：C:\Users\username\my_project\.venv\Scripts\python.exe

# 或使用 where 命令
where.exe python

五、在虚拟环境中管理第三方库

确认终端前缀显示 (.venv) 且 Python 路径指向项目目录后，即可使用 pip 安全地管理第三方依赖，而无需担心污染宿主系统。

1. 安装常用第三方库

在激活状态下的集成终端中执行安装命令：

# 安装单个库
pip install requests

# 安装指定版本
pip install pandas==2.1.4

# 同时安装多个依赖
pip install fastapi uvicorn

2. 检查当前虚拟环境已安装的依赖

# 查看当前环境中安装的所有包及其版本号
pip list

输出结果中仅会包含少量 pip、setuptools 基础包以及刚刚安装的第三方库，不会出现全局环境中的其他杂项，清晰可控。

3. 固化与还原项目依赖清单（requirements.txt）

在软件开发中，切勿将整个 .venv 目录上传到 Git 等代码版本管理仓库。正确的做法是导出依赖清单，并在新机器上通过清单重建环境：

# 将当前环境的所有第三方库名称与精确版本导出到文件
pip freeze > requirements.txt

# 新成员拉取代码后，在新建的 .venv 激活环境下执行
pip install -r requirements.txt

六、第三方库管理与团队协作全生命周期

为了让项目在个人开发与多人协作中始终保持一致，建议遵循标准生命周期规范。

七、常见问题排查与注意事项

1. Windows PowerShell 报错：无法加载文件 Activate.ps1，因为系统禁止运行脚本

原因：Windows 系统默认的 PowerShell 脚本执行策略为 Restricted，禁止运行未签名或外部脚本。

解决办法：无需以管理员身份更改系统全局策略，只需对当前用户授权即可。在 VS Code 终端中执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认后，重新打开终端即可顺利自动激活。

2. 终端里安装了库，但在 VS Code 编辑器中依然报“ModuleNotFoundError”或黄色下划线

原因：出现此问题通常是因为终端中激活的虚拟环境与 VS Code 当前选定的解释器不一致。例如：在终端中手动激活了 .venv，但 VS Code 右下角仍然选择了系统全局 Python，导致 Pylance 代码分析器未在 .venv/lib/site-packages 中检索模块。

解决办法：按快捷键 Ctrl+Shift+P -> 选择 Python: Select Interpreter -> 确认选择带有 ('.venv': venv) 的解释器。切换完成后，编辑器会在几秒内重新索引已安装的第三方库，警告波浪线随即消失。

3. 忽略文件配置：切勿将虚拟环境目录提交至 Git

虚拟环境包含平台相关的二进制执行文件与软链接，在不同操作系统或不同机器路径下无法直接运行。务必在项目根目录下的 .gitignore 文件中加入排除规则：

# 忽略 Python 虚拟环境目录
.venv/
venv/
ENV/
env/

# 忽略字节码缓存
__pycache__/
*.py[cod]

八、总结与速查清单

通过遵循上述规范，在 VS Code 中管理 Python 依赖不仅可以彻底杜绝包版本冲突，还能保证团队协作时环境构建的确定性与一致性。