VS Code配置Python开发环境及运行代码教程

刚开始用 Visual Studio Code 编写 Python 的开发者，经常会遇到这样的场景：新建了一个 .py 文件并写下 print("Hello World")，点击右上角运行却弹出“未找到解释器”的提示，或者在终端执行时报错“python 不是内部或外部命令”。配置 Python 环境的核心，就是理清代码编辑器、语言插件与本地解释器三者之间的分工与协作。完成本教程后，你将拥有一个开箱即用、支持代码补全、依赖隔离与断点调试的专业开发环境。

一、核心认知：编辑器、扩展与解释器的关系

许多初学者误以为安装了 VS Code 就能直接运行 Python，这是最常见的误区。VS Code 本身是一个轻量级的通用文本编辑器，并不内置 Python 运行时；而 Python 官方解释器才是真正负责将 Python 语法翻译为计算机指令的执行引擎。将二者连接起来的桥梁，是微软官方推出的 Python 扩展插件。

三者的协作机制如下：你在 VS Code 编辑器窗口中输入代码，Python 插件（配合 Pylance 语言服务器）为你实时提供智能补全、静态类型检查与错误高亮；当你触发运行或调试命令时，插件会调度指定的 Python 解释器启动子进程，并在内置终端中将代码执行结果完整呈现。

图 1：VS Code、Python 扩展与本地 Python 解释器分工协作架构图

二、环境准备：安装 Python 与 VS Code

进行配置前，需要确保本地计算机已经安装了 Python 解释器和 VS Code 客户端。以下是标准安装流程与关键细节。

1. 下载并安装 Python 解释器

访问 Python 官方网站（python.org），在 Downloads 导航区根据当前操作系统下载匹配的稳定版本安装包。安装时，务必注意以下关键配置：

• Windows 系统关键勾选项：在安装向导启动页面的底部，必须勾选 “Add python.exe to PATH”（将 Python 添加到系统环境变量）。若遗漏该选项，会导致系统命令提示符与 VS Code 无法自动识别 python 命令。
• macOS / Linux 系统：现代 macOS 和 Linux 发行版通常已预置 Python，建议通过 Homebrew（brew install python）或系统包管理器安装独立版本，避免污染系统内置环境。

2. 验证本地 Python 是否安装成功

打开系统的命令行终端（Windows 用户按 Win + R 输入 cmd，macOS 用户打开 Terminal），输入以下命令检查版本：

# 检查 Python 版本
python --version
# 或在部分 macOS/Linux 系统中执行：
python3 --version

# 检查包管理器 pip 版本
pip --version

如果控制台能够正常输出类似 Python 3.11.x 和 pip 24.x.x 的版本信息，说明本地解释器与环境变量均已就绪。

三、VS Code 安装 Python 核心扩展包

下载并启动 VS Code 后，需要安装由 Microsoft 维护的官方 Python 扩展包。该扩展是 VS Code 生态中最核心的开发工具包。

1. 点击 VS Code 左侧活动栏中的“扩展”图标（快捷键为 Ctrl + Shift + X，macOS 为 Cmd + Shift + X）。
2. 在顶部搜索框中输入 Python。
3. 找到发布者为 Microsoft 的扩展项，点击 Install（安装）。

安装主扩展时，VS Code 会自动捆绑安装 Pylance（提供智能语法补全与快速语法排错）以及 Python Debugger（提供调试协议适配支持）。安装完成后，无需重启软件即可生效。

图 2：VS Code 配置 Python 完整操作链路及六大核心步骤

四、创建工程工作区与虚拟环境配置

建议养成“以文件夹为工作区”的开发习惯，而不是在 VS Code 中单独打开单个散乱的 .py 脚本。以文件夹形式组织项目，能够让 VS Code 保持独立的配置上下文并自动隔离依赖。

1. 打开工作目录

点击菜单栏 文件 (File) -> 打开文件夹 (Open Folder)，选择一个空目录（例如 D:/workspace/python-demo 或 ~/projects/python-demo）。

2. 创建项目专属虚拟环境 (venv)

在实际开发中，直接将第三方库全部安装到全局系统 Python 会导致“依赖地狱”（例如不同项目需要不同版本的 Django 或 Pandas）。Python 内置的 venv 模块能在项目目录下创建独立的依赖沙箱：

按下快捷键 Ctrl + `（反引号）打开 VS Code 底部内置终端，输入以下命令：

# 在当前目录下创建名为 .venv 的虚拟环境沙箱
python -m venv .venv

命令执行完毕后，左侧资源管理器中会出现一个名为 .venv 的文件夹，里面包含了独立的 Python 可执行副本与 site-packages 目录。

3. 选择工作区 Python 解释器

这是最关键的配置步骤，决定了 VS Code 当前使用哪一个 Python 环境解析和执行代码：

1. 按快捷键 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出全局命令面板。
2. 在输入框中键入 Python: Select Interpreter 并按回车。
3. 列表中会列出自动发现的解释器。选择标注有 ('.venv': venv) 的选项；如果未自动列出，可点击 Enter interpreter path... 手动浏览至 .venv/Scripts/python.exe（Windows）或 .venv/bin/python（macOS/Linux）。

五、运行 Python 代码的四种常见方式

在项目根目录下新建一个名为 main.py 的文件，并粘贴以下测试代码：

def calculate_summary(scores):
    total = sum(scores)
    average = total / len(scores)
    return total, average

if __name__ == "__main__":
    student_scores = [88, 92, 79, 95, 84]
    total_score, avg_score = calculate_summary(student_scores)
    print(f"总分为: {total_score}, 平均分为: {avg_score:.2f}")

VS Code 提供了多种运行代码的方式，针对日常开发、交互测试和故障排查分别适用于不同模式：

图 3：VS Code 三大 Python 运行与调试机制的底层特性及适用场景对比

详细操作说明

• 右上角一键运行：在打开的 main.py 编辑界面右上角，找到向右的实心三角图标，点击 Run Python File。VS Code 将自动启动集成终端、激活虚拟环境并执行当前文件。
• 交互式选行运行：用鼠标选中 total_score, avg_score = calculate_summary(student_scores) 这一行，按下 Shift + Enter，右侧或下方会启动交互式终端，直接执行选中的代码行并保留当前变量状态。
• 断点调试：将鼠标悬停在第 3 行 average = total / len(scores) 的行号左侧，会出现一个淡红色圆点，单击变为鲜红实心圆点。此时按下 F5，程序运行到该行后会高亮挂起。左侧侧边栏会立即显示当前变量 total=438 和 scores 的列表详情，顶部会出现浮动调试工具条，支持逐步执行或继续执行。

六、常见配置报错与排查指南

在不同操作系统或不同环境安装过程中，可能会遇到特定配置阻碍。以下是四个最高频的报错现象与直接解决方案：

七、全景总结与最佳实践清单

配置好 VS Code 的 Python 开发环境不仅是一次性操作，更关乎长期的代码质量与维护成本。掌握正确的环境管理规范，能让后续的编码、协作与部署变得顺畅自然。

图 4：VS Code Python 开发环境四大最佳实践与避坑清单

按照本教程的流程与规范搭建好环境后，你在 VS Code 中的每一次运行与调试都将清晰可控。后续无论是进行数据分析、后端 Web 开发还是自动化脚本编写，只需在新工程中重复“打开目录 -> 创建 venv -> 选择解释器”这三步即可快速开启高效编码。