VS Code 配置 Python 开发环境：插件安装与解释器选择指南

Jasper

发布时间：2026-10-27| 5人浏览过

原创

Visual Studio Code（简称 VS Code）本身是一个轻量级通用代码编辑器，它既不内置 Python 运行环境，也不会在新建代码文件时自动执行。要在 VS Code 中获得完整的代码补全、智能提示与一键调试能力，关键在于完成两项核心配置：一是安装微软官方提供的 Python 插件组，二是为工作区正确绑定系统或虚拟环境中的 Python 解释器。本文将按照实际配置顺序，逐一讲解插件安装、解释器选择、虚拟环境联动以及常见运行报错的排查方法。

一、准备底座：系统 Python 环境确认

VS Code 并不自带 Python 运行时。在启动编辑器前，操作系统中必须已经独立安装了可用版本的 Python。首先打开系统自带的终端（Windows 的 PowerShell 或 CMD，macOS/Linux 的 Terminal），执行以下版本检测命令：

python --version
# 在部分 macOS 或 Linux 系统中若提示未找到命令，尝试：
python3 --version

终端如果返回类似 Python 3.11.x 或 Python 3.12.x 的版本编号，说明系统已具备基础运行环境。如果系统提示“命令未找到”或跳转至应用商店，则需先前往 Python 官方网站下载安装包。在 Windows 上安装时，务必勾选安装向导底部的 Add python.exe to PATH 选项，这一步决定了后续 VS Code 能否在系统中自动扫描到该解释器。

VS Code 配置 Python 开发环境：插件安装与解释器选择指南 — 图 1：VS Code 配置 Python 开发环境的标准四步执行路径

二、安装官方核心 Python 扩展插件

VS Code 通过插件系统提供针对具体语言的开发能力。对于 Python，最基础且不可或缺的是由微软官方维护的 Python 扩展（扩展 ID：ms-python.python）。

1. 插件安装步骤

打开 VS Code，点击左侧活动栏的 Extensions（扩展） 图标，快捷键为 Ctrl + Shift + X（macOS 用户按 Cmd + Shift + X）。
在顶部搜索框中直接输入 Python。
在搜索结果最顶端找到发布者为 Microsoft 的项目，点击右下角的 Install（安装） 按钮。

插件生态组合说明：当你安装 Microsoft 的 Python 插件时，VS Code 会自动关联安装 Pylance（提供快速准确的静态类型推断与代码补全）和 Python Debugger（负责断点调试与变量监视）。无需单独再去搜索和配置这些辅助组件。

三、核心操作：选择与绑定 Python 解释器

安装完插件后，打开任意以 .py 结尾的文件，VS Code 的语言服务就会被唤醒。此时的核心动作，是告诉 VS Code 应该调用磁盘上的哪一个 Python 程序来解析语法、加载模块和运行代码。这就是选择解释器（Select Interpreter）。

1. 打开解释器选择面板的两种途径

快捷键方式（最通用）：按下 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出顶部命令面板，输入 Python: Select Interpreter 并按回车。
状态栏快捷入口：当正在编辑 .py 文件时，观察 VS Code 窗口最底部的状态栏右下角（或左下角），会显示当前选择的 Python 版本（如 3.11.9 64-bit 或 Select Python Interpreter）。直接点击该文本，同样会唤起选择列表。

2. 面板中的解释器类型区别

调出解释器列表后，VS Code 会在弹窗中展示扫描到的所有 Python 安装位置。常见包括以下三类：

Global / System（全局解释器）：操作系统层级安装的 Python。如果你在此环境中通过 pip install 安装包，所有使用该解释器的脚本都会共享这些第三方库。长期开发容易造成版本冲突。
Virtual Environment（虚拟环境，如 .venv）：位于当前打开的工作区根目录下的隔离环境。这是 Python 官方与现代工程强烈推荐的做法，能确保不同项目之间的依赖库完全独立。
Conda Environment（Conda 环境）：由 Anaconda 或 Miniconda 管理的独立环境，常见于数据分析与机器学习项目。

如果你在列表中没有看到刚安装的 Python，可以点击列表第一项的 Enter interpreter path...（输入解释器路径），然后点击 Find...（浏览），手动定位到你系统中的 python.exe（Windows）或 python3 可执行文件路径即可。

四、最佳实践：为项目创建并自动识别虚拟环境

在实际开发中，推荐为每个项目单独创建虚拟环境。VS Code 具备对虚拟环境的自动感知机制。标准的操作顺序如下：

1. 打开项目文件夹

在 VS Code 中点击菜单栏 File（文件）> Open Folder...（打开文件夹），切勿直接单开一个独立的 .py 代码文件。打开文件夹后，VS Code 才能建立起以该目录为根节点的工作区配置。

2. 在内置终端中创建虚拟环境

按快捷键 Ctrl + `（反引号）打开 VS Code 集成终端，确保当前路径处于项目根目录下，执行内置虚拟环境创建指令：

# 在项目根目录下生成名为 .venv 的虚拟环境文件夹
python -m venv .venv

3. 响应自动切换提示

当 .venv 文件夹生成完毕后，VS Code 的 Python 插件通常会在窗口右下角弹出提示框：

“We noticed a new environment has been created. Do you want to select it for the workspace folder?”

此时点击 Yes，VS Code 会自动将当前工作区的解释器指针切换为该 .venv 环境。如果未弹出提示，可以手动按下 Ctrl + Shift + P，运行 Python: Select Interpreter，在列表中直接点选带有 ('.venv': venv) 标记的项。

五、运行验证：确认编辑器与终端环境一致

配置完成后，必须通过一段简单的代码来验证解释器是否正确生效，并确认代码运行所调用的 Python 路径与我们在状态栏所选定的路径完全一致。

1. 编写验证脚本

在项目根目录新建一个文件，命名为 check_env.py，输入以下内容：

import sys
import platform

print("=== Python 环境运行验证 ===")
print("操作系统平台:", platform.platform())
print("当前 Python 版本:", sys.version.split()[0])
print("当前生效的解释器绝对路径:")
print(sys.executable)

2. 执行脚本并查看输出

执行该文件有以下常用方法：

点击编辑器右上角的 ▷（Run Python File） 播放按钮；
在代码编辑区域右键，选择 Run Python > Run Python File in Terminal；
使用快捷键直接在终端运行。

执行后，VS Code 会自动在下方拉起终端，并自动执行虚拟环境激活命令（如 Windows 上的 .venv\Scripts\Activate.ps1 或 Linux/macOS 上的 source .venv/bin/activate），随后输出类似如下的内容：

=== Python 环境运行验证 ===
操作系统平台: Windows-10-10.0.19045-SP0
当前 Python 版本: 3.11.8
当前生效的解释器绝对路径:
D:\MyProject\.venv\Scripts\python.exe

核对输出中的解释器绝对路径。如果路径包含项目目录下的 .venv，说明当前工作区已经成功绑定到专属虚拟环境，环境配置完成。

六、高频问题与排查速查

在初次配置或多环境切换时，开发者常常会遇到报错。以下列出最常见的三种情况及解决步骤：

1. 为什么终端装了包，代码里还是报 `ModuleNotFoundError`？

这是新手阶段最容易遇到的“假象”问题。其根本原因在于：你在操作系统的全局终端中执行了 pip install requests，但 VS Code 此时绑定的是当前项目的 .venv 虚拟环境（或者反之）。两者拥有独立的 site-packages 目录，自然无法互相访问。

解决办法：在 VS Code 内部集成终端中，推荐使用 python -m pip install <库名> 来代替单独的 pip install。python -m pip 会严格保证调用当前处于激活状态的那个 Python 解释器对应的 pip 工具，避免包安装到了其他无关环境中。

2. Windows PowerShell 报错 `Activate.ps1 cannot be loaded because running scripts is disabled`

在 Windows 系统中，PowerShell 默认的安全执行策略是 Restricted，会阻止执行任何未签名或本地的脚本。要允许 VS Code 在打开终端时自动激活虚拟环境，可以以管理员身份运行 PowerShell，并执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

该策略仅对当前用户生效，既保障了操作系统核心安全，又解除了本地虚拟环境激活脚本的拦截。

总结

在 VS Code 中搭建高效的 Python 开发环境，其实质就是打通“编辑界面 - 官方扩展 - 目标解释器”三者之间的调用通路。牢记以下三个核心动作：

安装 Microsoft Python 扩展，获取代码高亮、补全分析（Pylance）及调试支持；
为每个项目创建独立虚拟环境（python -m venv .venv），保持依赖清晰受控；
使用命令面板（Ctrl+Shift+P）核准解释器路径，并通过打印 sys.executable 确保终端与编辑器指向同一个 Python 实体。