VS Code 中 Python 开发快速上手指南：从安装解释器到运行、调试与测试-平芜编程栈

文档
教程

【免费下载链接】vscode-docs

Public documentation for Visual Studio Code

项目地址：https://gitcode.com/gh_mirrors/vs/vscode-docs

本指南以 vscode-docs 仓库的官方快速入门文档（docs/python/python-quick-start.md）为骨架，完整讲解如何在 Visual Studio Code 中搭建 Python 开发环境：从安装编辑器、Python 扩展与解释器三件套，到创建项目文件、借助 Code Actions 修复代码、通过命令面板调用 Python 命令，最终实现运行、调试与测试 Python 代码的完整闭环。读完本文，你将掌握在 VS Code 中从零开始、高效完成 Python 日常开发的完整工作流，并了解如何进一步深入编辑、Lint、调试与测试等进阶能力。

开篇：三件套缺一不可的 Python 开发环境

Python 扩展让 Visual Studio Code 成为出色的 Python 编辑器，它支持任何操作系统，并能配合多种 Python 解释器使用。在开始之前，你需要依次安装三件独立的组件，它们各司其职、协同工作：

组件	作用	安装方式
Visual Studio Code	编辑器，负责编写和组织代码	从官网下载安装包
Python 扩展	为 VS Code 增加 Python 语言支持（IntelliSense、运行、调试等），但不包含 Python 本身	从 VS Code 扩展市场（Marketplace）搜索`ms-python.python`安装
Python 解释器	真正执行 Python 代码的程序，需独立安装	详见下文"安装 Python 解释器"

这三个部分的关系可以这样理解：VS Code 是工作台，Python 扩展把 VS Code 与 Python 连接起来，而解释器负责真正运行你的脚本。有关更通俗的说明，参见理解 Python 环境构成。

提示：安装完成后，你还可以利用 Python Profile 模板一键定制 VS Code——它会自动安装推荐的扩展与设置；如果是数据科学项目，则推荐使用 Data Science Profile 模板。

安装 Python 解释器

解释器的选择取决于你的具体需求，官方文档针对不同平台给出了以下指引：

Windows：从 python.org 使用Download Python按钮下载最新版本；若无管理员权限，也可通过 Microsoft Store 安装受支持的 Python 版本。
macOS：系统自带 Python 不被支持，推荐使用 Homebrew 包管理器，在终端执行brew install python3。同时请确保 VS Code 安装位置已加入 PATH 环境变量。
Linux：系统内置的 Python 3 可以直接使用，但安装其他包时需要先用 get-pip.py 安装pip。
其他选项：数据科学用户可考虑 Anaconda与 WSL 教程。

验证解释器是否安装成功

安装完成后，打开终端（Shell）执行以下命令验证：

# Linux / macOS python3 --version # Windows py -3 --version

若安装成功，终端会输出所安装的 Python 版本号。此外，在 VS Code 集成终端中运行py -0可列出机器上安装的所有 Python 版本，默认解释器以星号（*）标识。

注意：如果 Python 是在 VS Code 或终端已打开之后才安装的，请关闭并重新打开终端（或重启 VS Code）。终端在启动时才读取系统配置，只有全新的终端才能在你的PATH中找到新安装的 Python。

创建与打开 Python 项目或文件

已有 Python 项目时，可从 VS Code 欢迎页、文件资源管理器视图打开文件夹或文件，或使用File > Open Folder（kb(workbench.action.files.openFolder)）与File > Open File（kb(workbench.action.files.openFile)）菜单。

新建 Python 文件有两种入口：

在 VS Code 欢迎页选择New File，再选择Python file；
或通过File > New File（kb(workbench.action.files.newFile)）创建。

提示：如果工作区已打开一个文件夹，可以在文件资源管理器视图的顶层文件夹上使用New Folder或New File图标，把新文件/文件夹直接加入现有项目。

安装扩展后的界面导览

首次启动 VS Code 时，必须先安装 Python 扩展才能获得 Python 专属的功能与界面。安装完成后，界面中会新增大量 Python 相关的视图与入口，例如状态栏中的解释器选择器、活动栏中的测试烧杯图标、Python 侧边栏的环境管理等：

Code Actions：一键修复代码警告

Code Actions（又称 Quick Fixes，快速修复）用于在代码出现警告时帮助修复问题。这些提示会以灯泡图标的形式显示在编辑器左侧边距，点击灯泡即可查看可用的修复选项。Code Actions 可能来自 Python 扩展、Pylance 或 VS Code 本身，更多信息可参阅Python 快速修复。

通过命令面板访问 Python 命令

Python 扩展的全部命令都可以通过命令面板（kb(workbench.action.showCommands)）访问。在命令面板中输入"Python: "即可列出 Python 扩展提供的所有命令，例如Python: Select Interpreter、Python: Create Environment、Python: Start REPL、Python: Configure Tests等。

运行 Python 代码的四种方式

熟悉界面后，就可以开始运行代码了。VS Code 中运行 Python 有四种常用方式：

运行整个文件：点击编辑器右上角的Run Python File in Terminal播放按钮。该按钮会打开一个终端面板，自动激活所选 Python 解释器，然后执行python3 hello.py（macOS/Linux）或python hello.py（Windows）。
运行选中代码：选中一行或多行后按kbstyle(Shift+Enter)，或右键选择Run Selection/Line in Python Terminal，适合只测试文件的一部分。
Smart Send 智能发送：不选中任何内容、光标停留某行时按kbstyle(Shift+Enter)，扩展会把光标附近最小可运行的代码块发送到 Python REPL，并把光标移动到下一行（默认开启；若只想按光标所在行发送，可在设置中把python.REPL.enableREPLSmartSend设为false）。
启动 REPL：从命令面板（kb(workbench.action.showCommands)）选择Python: Start REPL，为当前选中的解释器打开一个以>>>提示符标识的 REPL 终端，逐行输入并运行代码。

关于 REPL 的更多细节，运行 Python 代码文档还介绍了Python: Start Native REPL（原生 REPL，带 IntelliSense 与语法高亮，可通过python.REPL.sendToNativeREPL设置切换 Smart Send 的发送目标）与终端 Shell 集成等特性，可作为深入学习参考。

调试：从断点到变量跟踪

调试器让你能检查代码执行流程、更轻松地定位错误，并观察程序运行过程中变量与数据的动态变化。调试流程如下：

设置断点：在要检查的代码行左侧装订线（gutter）处单击，或光标置于该行后按kb(editor.debug.action.toggleBreakpoint)，装订线会显示红色圆点。

启动调试：按kbstyle(F5)。首次调试该文件时，会弹出配置菜单让你选择要调试的应用类型；如果是 Python 脚本，选择Python File即可。调试配置以 JSON 形式保存在标准命名的launch.json文件中（完整说明见调试配置）。调试支持由 Python Debugger（debugpy）扩展提供，它会随 Python 扩展自动安装，可在扩展视图中搜索@installed python debugger确认。
单步执行与观察变量：程序到达断点后会暂停，此时可在 Python 调试控制台（Debug Console）跟踪数据，并使用调试工具栏（Debug Toolbar）控制执行——从左到右依次为：继续、单步跳过、单步进入、单步退出、重启、停止。调试期间状态栏会变为橙色（多数主题下），Python 调试控制台会自动出现在右下方面板中，显示正在执行的命令与程序输出。

在调试控制台的>提示符下，你可以逐条输入表达式求值，例如msg、msg.capitalize()、msg.split()。程序运行未完成时，可用调试工具栏的红色方块停止按钮或Run > Stop debugging菜单终止调试。调试功能的深入用法（如远程调试、指定解释器调试、Logpoints 日志点替代 print 等）见 Python 调试指南。

测试：配置、发现、运行与调试

Python 扩展为 unittest 与 pytest 两大测试框架提供了完善的测试支持（pytest 最低支持版本为 7.0.0）。启用测试的入口有两个：

Testing 视图：活动栏上的测试烧杯图标即 Testing 视图。若尚未启用测试框架，视图中会出现Configure Python Tests按钮，点击后选择测试框架与存放测试的文件夹；使用 unittest 时还需指定识别测试文件的 glob 模式。
命令面板：随时可用Python: Configure Tests命令配置，或在设置编辑器 /settings.json中设置python.testing.unittestEnabled或python.testing.pytestEnabled。

测试发现规则如下：

python.testing.unittestArgs：在项目顶层文件夹查找文件名含 "test" 的.py文件（所有测试文件必须是可导入的模块或包），可用-p定制文件匹配模式、-t定制文件夹；
python.testing.pytestArgs：查找当前文件夹及其所有子文件夹中文件名以test_开头或_test结尾的.py文件。

配置完成后，扩展会自动尝试发现项目中的测试；你可以在 Testing 视图中运行、调试测试，并在测试结果（Test Results）面板中查看运行输出。若同时启用两个框架，扩展只运行 pytest；若启用 pytest 但当前环境未安装，扩展会在后台尝试安装。测试配置、覆盖率运行（pytest 下基于pytest-cov、unittest 下基于coverage.py）、并行测试（pytest-xdist）等进阶内容见 Python 测试指南。