VSCode怎么用venv虚拟环境跑python

一、为什么建了环境却依然无法调用：认识解释器绑定

初次在 VS Code 里开发 Python 时，经常出现一个典型细节：明明已经在系统终端里执行了创建虚拟环境的命令，但在 VS Code 编辑器里打开代码文件，第三方的 import 语句依然下划红线提示 ModuleNotFoundError，点击右上角运行按钮输出的也是全局 Python 的报错信息。

导致该现象的根本原因在于：生成虚拟环境文件夹与 VS Code 识别解释器是两个独立的动作。VS Code 是一个多语言通用编辑器，其运行 Python 脚本的依据是 Python 扩展所指向的“当前活动解释器路径（Selected Interpreter）”。如果未在编辑器内部指定环境，VS Code 就会默认回退到全局系统的 Python 解释器，根本不会调用项目本地刚创建的虚拟环境。

如上图所示，全局环境的 site-packages 会随时间推移积累不同项目安装的依赖，极易产生依赖破坏。通过在项目目录下建立专用的 .venv 目录，配合 VS Code 将解析和运行指针重定向到该环境下的可执行文件，即可实现完全独立的开发沙箱。

二、VS Code 运行 venv 虚拟环境的四步实操流程

从零开始配置一个受虚拟环境托管的 Python 项目，整个链路遵循清晰的先后顺序。下面的步骤图梳理了从打开项目根目录到最终执行验证的完整闭环。

第 1 步：在 VS Code 中打开项目根目录

打开 VS Code 后，必须通过菜单栏的 文件 > 打开文件夹（macOS 为 File > Open Folder），选中你的项目目录作为工作区（Workspace）。

这一步非常关键。VS Code 的 Python 扩展在扫描和识别解释器时，默认以当前工作区根目录为基准进行浅层与深层匹配。如果只是单独打开了单个 .py 文件而没有打开文件夹，VS Code 将处于无工作区模式，无法持久化项目级别的解释器设置。

第 2 步：在内置终端中创建 venv 虚拟环境

使用快捷键 Ctrl + `（macOS 为 Cmd + `）打开 VS Code 的集成终端。确认终端当前路径位于项目根目录后，执行 Python 标准库自带的 venv 模块命令：

macOS / Linux 系统：

python3 -m venv .venv

Windows 系统：

python -m venv .venv

第 3 步：绑定 Python 解释器（Select Interpreter）

创建完 .venv 目录后，VS Code 右下角有时会弹出提示询问是否将其设为工作区默认环境。若未弹出提示或错过了气泡，按以下标准流程手动绑定即可：

1. 使用快捷键 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出顶部命令面板（Command Palette）。
2. 在输入框中输入 Python: Select Interpreter，并按下回车。
3. 在弹出的解释器列表中，找到带有 Recommended（推荐）标识的项。其路径应显示为 ./.venv/bin/python（macOS/Linux）或 .\.venv\Scripts\python.exe（Windows）。
4. 点击该项完成选定。

选定后，VS Code 会在当前项目根目录下的 .vscode/settings.json 文件中自动写入或更新配置：

{
  "python.defaultInterpreterPath": ".venv/bin/python"
}

这一机制确保了即使重启编辑器或下一次重新打开该文件夹，VS Code 也会自动继承该虚拟环境，无需重复选择。

第 4 步：激活终端并运行 Python 代码

配置好解释器后，在 VS Code 的集成终端面板中，点击右上角的 + 号新建一个终端窗口。VS Code 会根据刚才选定的解释器，自动向新终端注入激活环境脚本。

此时可以清晰地看到终端命令提示符的最前方出现了环境标识符：

(.venv) user@machine:~/my-project$ 

一旦看到 (.venv) 前缀，即代表后续的所有命令（包括 pip install）都会严格安装并运行在该虚拟环境内。

三、验证运行：编写测试代码确认隔离生效

为了百分之百确认当前运行环境正是项目目录下的 .venv，而不是系统全局 Python，可以在项目根目录下新建一个验证文件 verify_env.py，编写如下测试代码：

import sys

def check_environment():
    executable_path = sys.executable
    print("=" * 50)
    print("当前实际执行的 Python 解释器路径:")
    print(executable_path)
    print("=" * 50)
    
    # 逻辑判断：路径中是否包含 .venv
    if ".venv" in executable_path:
        print("[SUCCESS] 验证成功：当前代码正在 .venv 虚拟环境中运行！")
    else:
        print("[WARNING] 警告：当前代码仍在使用全局解释器运行，请检查 VS Code 解释器选择。")

if __name__ == "__main__":
    check_environment()

在 VS Code 中有两种便捷的运行方式：

• 方式一（编辑器图形按钮）：直接点击编辑器右上角的三角箭头“运行 Python 文件（Run Python File）”按钮。VS Code 会自动拉起终端并传入完整路径执行。
• 方式二（命令行直接执行）：在已经带有 (.venv) 前缀的集成终端中，直接输入命令 python verify_env.py 并回车。

执行后的示例输出如下所示：

==================================================
当前实际执行的 Python 解释器路径:
/Users/developer/my-project/.venv/bin/python
==================================================
[SUCCESS] 验证成功：当前代码正在 .venv 虚拟环境中运行！

只要输出的路径中包含当前项目下的 .venv 文件夹层级，就证明虚拟环境已全面接管执行与调试。

四、高频异常排查与检查闭环

在实际使用中，受操作系统安全策略、默认终端类型或环境缓存影响，可能会出现一些特定阻碍。下图整理了从异常现象到解决动作的排查闭环：

1. Windows PowerShell 提示禁止运行脚本（ExecutionPolicy）

在 Windows 系统下打开新终端时，若出现红色报错 File ... activate.ps1 cannot be loaded because running scripts is disabled on this system，是因为 Windows 默认的安全策略禁止执行未签名的 PowerShell 脚本。

解决方法：在 Windows 搜索框搜索 PowerShell，右键“以管理员身份运行”，执行以下命令放行本地脚本：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

按下 Y 确认后，返回 VS Code 关闭旧终端并重新打开一个终端即可正常自动激活。

2. 新建终端没有显示 (.venv) 前缀

如果右下角已经选中了虚拟环境，但新建终端始终没有激活前缀，通常是因为旧的终端进程缓存未刷新，或者全局设置关闭了自动激活特性。

解决方法：

• 首先尝试彻底关掉所有正在运行的终端标签页（点击垃圾桶图标），然后点 + 重新创建。
• 如果仍未激活，可以在终端手动执行一次对应的激活命令：
  • Linux / macOS: source .venv/bin/activate
  • Windows CMD: .venv\Scripts\activate.bat
  • Windows PowerShell: .venv\Scripts\Activate.ps1

3. 编辑器代码飘红与运行结果不一致

有时在终端中运行代码完全正常，但编辑器中的代码却依旧标红提示未安装该模块。这是由于 VS Code 的代码分析语言服务（Pylance）尚未重新索引新的环境路径。

此时只需再次按下 Ctrl + Shift + P，输入 Python: Restart Language Server（重启语言服务器），Pylance 会重新读取 .venv 下的 site-packages，编辑器中的警告红线便会即刻消失。

五、规范化的开发实践

在日常工程开发中，建议为每一个独立项目建立专属的 .venv，并养成良好的版本管理习惯：

• 加入 .gitignore：虚拟环境包含大量与具体机器、操作系统绑定的二进制可执行文件及体积庞大的三方包，切勿将其提交到 Git 仓库。在项目根目录的 .gitignore 文件中必须显式写入 .venv/。
• 依赖文件固化：通过 pip freeze > requirements.txt 记录项目所需的模块与版本号。团队其他成员拉取代码后，只需执行 python -m venv .venv 并通过 pip install -r requirements.txt，即可在数秒内复现完全一致的开发环境。