在 VS Code 中配置 Python 虚拟环境(venv/Conda)的步骤

何川

发布时间：2026-10-20 | 4人浏览过

原创

在 Visual Studio Code（简称 VS Code）中进行 Python 开发时，配置虚拟环境能够实现项目依赖隔离，避免不同工程因三方库版本冲突而产生异常。在 VS Code 中配置虚拟环境的核心逻辑，是让 VS Code 的 Python 扩展指向虚拟环境内的解释器可执行文件（python.exe 或 python），并确保新建集成终端时能自动执行激活脚本。无论使用 Python 内置的 venv 还是面向科学计算的 Conda，核心操作都可以明确归纳为：准备工作区、生成虚拟环境、通过命令面板绑定解释器、新建终端验证激活。以下是完整的操作步骤与排查说明。

一、准备工作与工作原理

VS Code 本身是一个通用代码编辑器，它并不自带 Python 运行时环境，所有语法分析、代码自动补全、格式化与环境识别功能均依赖于扩展插件。因此在配置前需确认完成两项准备：

安装官方 Python 扩展：在 VS Code 左侧扩展市场（Extensions）中搜索并安装由 Microsoft 发布的 Python 扩展包（ms-python.python）。
使用文件夹方式打开项目：在 VS Code 中依次点击“文件” > “打开文件夹（Open Folder）”，将工程所在目录载入工作区。单文件打开模式下 VS Code 无法将解释器配置持久化保存到项目目录。

当通过 VS Code 选择解释器后，编辑器会在工程根目录生成或更新 .vscode/settings.json 配置文件，写入 python.defaultInterpreterPath 指向目标解释器。后续每当在此项目中新建终端，VS Code 都会自动读取该配置并执行对应的环境变量激活操作。

在 VS Code 中配置 Python 虚拟环境(venv/Conda)的步骤

图 1：VS Code 与 Python 全局及隔离环境交互架构图

二、配置 venv 虚拟环境的详细步骤

venv 是 Python 3.3+ 官方标准库内置的轻量级虚拟环境模块，无需额外安装任何工具包。将 venv 配置到 VS Code 的过程包含四个标准步骤：

步骤 1：在项目根目录下创建虚拟环境

在 VS Code 顶部菜单栏点击“终端（Terminal）” > “新建终端（New Terminal）”，确保当前终端的工作目录为当前项目根目录。根据操作系统输入对应命令：

# Windows 系统（CMD 或 PowerShell）
python -m venv .venv

# macOS / Linux 系统（通常调用 python3）
python3 -m venv .venv

执行完成后，项目根目录下将出现一个名为 .venv 的文件夹。该目录内包含一个独立的 Python 可执行副本、标准库链接以及独立的 site-packages 第三方库存放目录。

步骤 2：在 VS Code 中调出命令面板选择解释器

通常情况下，Python 扩展会检测到根目录新生成的 .venv 文件夹，并在右下角弹出提示询问是否将其选为工作区环境。若未弹出或需要手动指定，按下快捷键唤起命令面板：

Windows / Linux：按下 Ctrl + Shift + P
macOS：按下 Cmd + Shift + P

在输入框中键入 Python: Select Interpreter 并按回车。系统会列出已扫描到的所有解释器列表。

步骤 3：选中目标虚拟环境

在弹出的列表中，优先选择带有 Recommended 或 .venv: ('venv') 标识的选项。其对应路径通常为：

Windows：.\.venv\Scripts\python.exe
macOS / Linux：./.venv/bin/python

如果列表中没有自动列出该路径，可点击列表首项的“Enter interpreter path...（输入解释器路径）” > “Find...（浏览查找）”，手动定位到上述路径中的 python 可执行文件并确认。

步骤 4：新建集成终端触发自动激活

关键细节提醒：已经在运行中的旧终端不会动态刷新环境变量。必须关闭旧终端或点击终端面板右上角的“+”号新建一个终端，才能触发自动激活。

新建终端启动后，若命令行最左侧出现 (.venv) 前缀（例如 (.venv) PS C:\my_project>），即表明该虚拟环境已经成功激活。此时运行 pip install package_name 将所有依赖直接安装到 .venv/Lib/site-packages 中，完全与系统环境隔离。

图 2：在 VS Code 中创建并配置 venv 虚拟环境的标准步骤

三、配置 Conda 虚拟环境的步骤

Conda（包括 Anaconda 和轻量级的 Miniconda）是一套跨平台的包管理与环境管理系统，广泛应用于数据分析、机器学习与深度学习领域。与 venv 不同，Conda 环境默认集中存储在 Conda 安装目录下的 envs 文件夹中，而非存放在当前项目根目录下。

步骤 1：创建专用的 Conda 环境

在系统终端或已配置好 Conda 的 VS Code 终端中执行环境创建命令，可根据需求直接指定 Python 版本：

# 创建指定 Python 版本的 Conda 环境（名称为 my_ai_env）
conda create --name my_ai_env python=3.10 -y

该命令会在 Conda 的集中式环境目录中（例如 ~/miniconda3/envs/my_ai_env 或 C:\ProgramData\miniconda3\envs\my_ai_env）构建一套完整的运行依赖。

步骤 2：在 VS Code 解释器列表中选择 Conda 环境

按下快捷键 Ctrl + Shift + P（macOS 上为 Cmd + Shift + P），输入并执行 Python: Select Interpreter。VS Code 的 Python 扩展会自动调用系统中的 conda 指令枚举出所有已注册环境。在列表中会显示格式如下的选项：

Python 3.10.x ('my_ai_env': conda)  ~/miniconda3/envs/my_ai_env/bin/python

直接点击该条目，VS Code 会将该解释器路径与 Conda 环境名称记录到当前工作区设置中。

步骤 3：在集成终端中自动执行 conda activate

新建集成终端，VS Code 会自动在后台发起激活指令：

conda activate my_ai_env

此时终端提示符前缀会由基础环境 (base) 或无前缀转变为 (my_ai_env)，表明当前终端已经切换至目标 Conda 环境的上下文。

图 3：Conda 环境在 VS Code 中的识别与激活机制

四、验证配置有效性的三种方式

完成配置后，不能仅凭感觉判断是否生效，可以通过以下三个位置进行交叉验证：

查看 VS Code 状态栏信息：在 VS Code 窗口底部的状态栏（右下角或左侧），找到 Python 版本标识。正常生效时，该区域会明确显示 Python 3.x.x ('.venv': venv) 或 Python 3.x.x ('my_ai_env': conda)。点击该标识也可以直接快速呼出解释器选择面板。
检查新终端的命令提示符前缀：新建终端后，命令行首部应带有环境名称括号，如 (.venv) 或 (my_ai_env)。
运行代码打印解释器绝对路径：在集成终端中执行单行验证命令，查看当前调用的 Python 实体是否确属虚拟环境路径：
```
python -c "import sys; print('解释器绝对路径:', sys.executable); print('环境根目录:', sys.prefix)"
```
若打印输出的路径包含 .venv 或 miniconda3/envs/...，则说明当前终端与编辑器的运行环境完全配置正确。

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

1. Windows PowerShell 报错：“因为在此系统上禁止运行脚本”

在 Windows 环境下使用 VS Code 默认的 PowerShell 终端时，首次激活虚拟环境常出现如下红色报错：

File C:\project\.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system.

原因：Windows 默认的 PowerShell 执行策略（ExecutionPolicy）为 Restricted，禁止运行未签名脚本。
解决方法：以管理员身份运行 PowerShell，执行以下命令放宽当前用户脚本执行权限：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

执行完成后重启 VS Code 并重新打开终端即可正常加载 Activate.ps1。

2. 解释器列表中找不到刚创建的 Conda 环境

原因：VS Code 依赖 PATH 环境变量中的 conda 指令来扫描所有环境。如果安装 Anaconda / Miniconda 时没有勾选将 Conda 添加至系统环境变量，VS Code 便无法自动定位。
解决方法：在命令面板选择 Python: Select Interpreter > Enter interpreter path... > Find...，直接定位到 Conda 安装根目录下的 conda.exe，或者直接浏览并选中目标环境目录下的 python.exe（例如 C:\Users\username\miniconda3\envs\my_ai_env\python.exe）。选中一次后，VS Code 将持续记住该解释器。

3. Git 版本控制中的忽略配置

如果使用的是项目目录下的 venv 环境（如 .venv），务必在项目根目录的 .gitignore 文件中加入该文件夹名称：

# 忽略本地虚拟环境
.venv/
venv/
ENV/

虚拟环境包含平台特异的二进制文件和数以千计的三方库，体积庞大且不具备跨机移植性。团队协作时应仅提交 requirements.txt 或 environment.yml，由协作者在本地根据清单自行重新生成环境。

图 4：venv 与 Conda 选型对比及配置后三重验证核对表

六、总结

在 VS Code 中正确配置虚拟环境是规范化 Python 工程管理的第一步。对于常规 Web 应用、小工具开发或轻量级工程，直接在项目根目录下通过 python -m venv .venv 创建环境是最简洁、无额外依赖的最佳实践；对于涉及跨语言依赖、底层 C/C++ 库或特定 Python 版本的科学计算与深度学习工程，使用 conda create 创建集中式环境则更为高效稳定。掌握通过 Python: Select Interpreter 进行绑定以及利用状态栏、终端前缀与 sys.executable 进行验证的方法，即可彻底告别依赖冲突与环境混乱问题。