怎么在 VS Code 中激活虚拟环境运行 Python 项目
详细介绍怎么在 Visual Studio Code (VS Code) 中选择解释器、激活虚拟环境（venv/.venv）并正确运行与调试 Python 项目，涵盖联动架构、完整操作步骤、终端验证及常见故障排查。
在 VS Code 中激活虚拟环境运行 Python 项目，本质是告诉 VS Code 当前项目工作区应该绑定哪个 Python 解释器。核心操作只需两步：打开项目根目录后，通过命令面板选择 Python: Select Interpreter 指向虚拟环境内的 Python 执行文件；随后新建或重新打开内置终端，VS Code 就会根据选中的解释器自动执行激活脚本，使终端与编辑器在同一个隔离环境中运行代码。
一、理解 VS Code 与虚拟环境的联动机制
许多初学者容易产生一个误解：以为在系统终端里执行了 activate 命令，VS Code 编辑器就自动知晓该环境了。实际上，VS Code 包含两套相互协作但机制独立的子系统：一个是负责代码提示、语法检测、断点调试的“编辑器语言服务”，另一个是底层的“内置终端（Integrated Terminal）”。
为了让代码运行和编辑器提示都使用同一个虚拟环境，VS Code 官方的 Python 扩展提供了解释器选定机制。一旦指定了虚拟环境中的 Python 文件，扩展程序就会在当前项目下的 .vscode/settings.json 记录路径，并在用户唤起新终端时，自动注入环境变量或执行配套的激活脚本。
二、激活虚拟环境的标准操作步骤
整个配置流程从打开项目目录开始，到新建终端并确认环境前缀结束。操作规范且可复现，具体分为四个阶段。
步骤 1：以“文件夹”形式打开项目根目录
VS Code 的环境隔离是基于工作区（Workspace）生效的。务必使用菜单栏的 File -> Open Folder（文件 -> 打开文件夹）直接打开项目根目录，而不是仅仅打开单个 .py 文件。
如果项目中尚未创建虚拟环境，可以在项目根目录下打开系统终端，使用 Python 内置的 venv 模块快速创建一个标准的虚拟环境：
python3 -m venv .venvpython -m venv .venv
推荐使用 .venv 作为目录名。VS Code 的 Python 扩展默认会自动递归扫描根目录下名为 .venv、venv 或 env 的文件夹，从而无需手动查找即可智能推荐。
步骤 2：打开命令面板选择 Python 解释器
在 VS Code 窗口中，按下快捷键唤出全局命令面板：
- Windows / Linux：按下
Ctrl + Shift + P - macOS：按下
Cmd + Shift + P
在顶部弹出的输入框中，键入 Python: Select Interpreter（选择解释器）并回车。
步骤 3：选中项目专属的虚拟环境
执行命令后，VS Code 会列出检测到的全部解释器列表：
- 自动识别项：如果之前已经在项目根目录下建立了
.venv，列表中第一项通常会显示带有Recommended（推荐）或者('.venv': venv)标识的项，直接鼠标单击选中即可。 - 手动指定路径：如果列表没有自动展示新建的环境，点击列表顶部的
Enter interpreter path...（输入解释器路径），随后点击Find...（浏览），定位并选中虚拟环境中的 Python 可执行文件：- macOS / Linux：选择项目目录下的
.venv/bin/python - Windows：选择项目目录下的
.venv\Scripts\python.exe
- macOS / Linux：选择项目目录下的
选择完成后，VS Code 窗口最底部的状态栏右下角会立即更新显示所选的解释器名称，例如 3.11.x ('.venv': venv)。
步骤 4：新建内置终端验证自动激活
选择解释器后，注意已有的旧终端窗口不会自动热重载。必须新建一个终端窗口以触发激活钩子：
- 点击顶部菜单栏的
Terminal -> New Terminal（终端 -> 新建终端），或按下快捷键Ctrl + `。 - 观察新终端命令提示符的最左侧。如果成功激活，命令行提示符前端会出现括号包裹的环境名，例如
(.venv)。
为确保运行环境无误，可在终端中执行路径查询命令进行最终验证：
macOS / Linux 验证命令which python
# 正确返回示例：/Users/username/myproject/.venv/bin/pythonwhere.exe python
# 正确返回示例：C:\projects\myproject\.venv\Scripts\python.exe
若命令返回的路径明确指向当前项目内的 .venv 文件夹，说明当前终端已经处于隔离虚拟环境内。
三、在已激活的环境中运行与调试代码
当解释器与终端完成绑定后，在 VS Code 中运行 Python 项目主要有以下三种标准方式：
| 运行方式 | 操作位置 | 执行机制与特点 |
|---|---|---|
| 右上角 Run 按钮 | 打开 main.py 后点击右上角三角形播放图标 |
VS Code 自动在终端中调用选定解释器执行该脚本，最简单直观。 |
| 终端交互命令 | 在底部已激活的终端中键入命令 | 直接执行 python main.py 或安装依赖 pip install -r requirements.txt，支持任意命令行参数。 |
| VS Code 调试器 (F5) | 按下 F5 或在“运行与调试”面板启动 |
依据 .vscode/launch.json 配置运行，断点调试完全基于虚拟环境内的依赖与源码。 |
如果你希望将环境路径共享给团队成员或避免重复配置，可以在项目根目录创建 .vscode/settings.json 文件，并写入相对路径：
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}
在 Windows 环境下将路径对应修改为 "${workspaceFolder}\.venv\Scripts\python.exe"。配置后，任何人用 VS Code 打开此项目，扩展都会自动优先识别该路径。
四、常见问题排查与解决办法
在实际配置过程中，由于操作系统安全策略或终端缓存，可能会遇到未自动激活或路径未加载的问题。以下是三种最高频故障的针对性排查手段。
1. Windows PowerShell 报错“无法加载脚本，因为系统禁止运行脚本”
在 Windows 系统下打开新终端时，如果终端报红并提示 File ... Activate.ps1 cannot be loaded because running scripts is disabled on this system，这是因为 PowerShell 默认执行策略为 Restricted。
解决方法：在 VS Code 终端或以普通用户身份打开 PowerShell 窗口，执行以下命令将当前用户的执行策略调整为 RemoteSigned：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行完毕后，关闭当前终端窗口并重新打开一个新终端，即可正常自动激活。
2. 新建终端没有出现 (.venv) 前缀
如果状态栏已经选好了虚拟环境，但打开新终端依然没有括号前缀，请依次检查以下两点：
- 确认自动激活开关未关闭：打开 VS Code 设置（
Ctrl + ,/Cmd + ,），搜索python.terminal.activateEnvironment，确保该配置项处于勾选状态（默认开启）。 - 关闭复用的旧终端：VS Code 会在重新启动时恢复之前的终端会话。点击终端面板垃圾桶图标彻底关闭旧会话，重新点击
Terminal -> New Terminal。
3. 终端已通过 pip 安装了模块，但代码中依然提示“未解析的导入 (Unresolved import)”
这种情况说明“VS Code 语言服务器使用的解释器”与“终端实际执行 pip 的 Python 环境”脱节。
排查与修复：
- 在终端中运行
pip -V，核对返回路径中的site-packages是否在项目.venv内。 - 核对 VS Code 底部状态栏显示的解释器是否也是同一个
.venv。 - 若两者一致但波浪线警告仍未消失，按
Ctrl+Shift+P唤出命令面板，执行Python: Restart Language Server（重启语言服务器）强制刷新缓存。
本站声明
本文内容仅供参考，不代表本站观点。转载或引用请注明出处。如发现内容问题，请通过联系我们页面反馈。
