VS Code编写Python源文件的初始配置指南

在本地计算机已经安装好 Python 运行环境和 Visual Studio Code（以下简称 VS Code）之后，很多初学者在直接新建文件编写代码时，常会遇到没有语法补全、无法直接点击运行或提示缺少解释器等困扰。VS Code 本身是一个高度轻量化的通用代码编辑器，它对 Python 语言的支持完全建立在模块化扩展与工作区配置机制之上。本文将梳理一条清晰明了的初始配置路径：从安装官方核心扩展、建立专用项目工作区、正确绑定 Python 解释器，到编写首个源文件并执行验证，帮助你建立规范、稳定的 Python 编写环境。

一、准备工作与安装核心扩展

完成初始配置的第一步，是让 VS Code 具备理解 Python 语法的能力。默认状态下的 VS Code 仅将 .py 文件视作纯文本。我们需要安装微软官方维护的 Python 扩展套件。

打开 VS Code，通过左侧活动栏的积木图标（快捷键 Ctrl+Shift+X 或 macOS 下的 Cmd+Shift+X）进入扩展市场。在搜索框输入 Python，找到由 Microsoft 官方发布的扩展项并点击“安装（Install）”。

安装此主扩展时，VS Code 会自动附带安装 Pylance（提供强大的代码静态分析、类型检查和自动补全）以及 Python Debugger。这套工具链构成了编写与调试 Python 代码的基础支撑。

图 1：VS Code 编写 Python 源文件初始配置四阶段操作全流程

二、建立独立的工作区目录

很多初学者容易犯的第一个习惯性错误是：直接在桌面上右键新建一个文件并用 VS Code 打开。在 VS Code 的机制中，如果单纯打开单个文件，编辑器处于未加载工作区状态，不仅无法持久化当前项目的解释器设定，后续的多模块导入和代码跳转也容易失效。

正确的规范做法是：以文件夹形式打开工作区。

1. 在磁盘指定位置（例如 D:/Projects/PythonDemo 或 macOS/Linux 用户的 ~/Projects/PythonDemo）建立一个纯英文命名的空文件夹。注意避免目录中带有中文、空格或特殊字符。
2. 在 VS Code 顶栏点击 文件 (File) -> 打开文件夹... (Open Folder...)，选中刚刚创建的文件夹。
3. 在弹出的“是否信任此文件夹中的作者”对话框中，勾选信任选项并点击确认。

打开文件夹后，左侧资源管理器会显示该文件夹名称作为根目录。VS Code 在后续产生针对该项目的个性化配置时，会自动在此目录下生成 .vscode/settings.json 文件。

三、核心关键：选择并绑定 Python 解释器

安装了扩展并不等于配置完成。VS Code 只负责前端编辑，真正执行 Python 源码需要操作系统中的 python.exe（或 macOS/Linux 下的 python3）解释器程序。此时必须显式为当前工作区绑定解释器。

1. 触发解释器选择菜单

按下快捷键 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出全局命令面板（Command Palette），在输入框中键入：

Python: Select Interpreter

在下拉列表中点击运行该命令。

2. 识别候选解释器类型

命令面板中会列出当前系统扫描到的所有 Python 安装版本：

• 全局系统解释器（Global）：通常位于 C:\Python311\python.exe 或 /usr/local/bin/python3。如果是初学简单语法，可以直接选中它。
• 虚拟环境（Virtual Environment，如 venv / .venv）：若项目中创建了虚拟环境，会标注出 ('venv': venv)。在现代 Python 开发中，推荐针对项目建立独立的虚拟环境。
• Conda 环境：若安装了 Anaconda 或 Miniconda，列表中会显示 base (conda) 等标签。

图 2：VS Code 与 Python 运行架构分层及配置映射机制

四、编写首个 Python 源文件并执行验证

完成前置两项配置后，便可以开始创建实际的代码源文件进行实测验证。

1. 新建源文件

在左侧资源管理器中，点击工程根目录右侧的“新建文件”图标（或在文件树空白处右键选择“新建文件”），命名为 hello.py。必须保留 .py 后缀，VS Code 依靠扩展名判断文件语言类型。

2. 输入示例验证代码

在打开的编辑器区域中，输入以下标准 Python 验证代码：

import sys

def main():
    print("Python 初始配置验证成功！")
    print(f"当前使用的解释器路径: {sys.executable}")
    print(f"Python 核心版本: {sys.version.split()[0]}")

if __name__ == "__main__":
    main()

输入过程中，如果 Pylance 扩展工作正常，在键入 sys. 时会立即弹出代码自动补全悬停窗；同时语法高亮会清晰区分关键字、函数名与字符串。

3. 执行与验证方式

在 VS Code 中执行 Python 源文件主要有以下三种方式：

• 右上角运行按钮（推荐）：在编辑器窗口的右上角，找到带有小箭头的三角图标（▶）。点击下拉菜单选择“在终端中运行 Python 文件（Run Python File）”。
• 编辑器内右键快捷执行：在编辑区域任意代码空白处点击鼠标右键，选择“在终端中运行 Python 文件”。
• 集成终端直接运行：通过快捷键 Ctrl+`（反引号）打开 VS Code 底部集成终端，在命令行手动输入命令：

  python hello.py

图 3：代码编辑、触发运行与集成终端回显交互全过程

五、初始配置常见问题排查与注意事项

初次配置过程中，若遇到异常报错或无法正常执行，通常集中在以下几个关键节点。读者可根据具体现象对照下表排查：

六、环境配置清单与总结

为确保后续编写 Python 代码顺畅，可随时对照下述关键检查清单，确认你的初始配置处于完全健康的状态：

图 4：VS Code 编写 Python 初始配置关键检查清单与状态总览

完成上述配置后，你的 VS Code 已经不再是单纯的文本编辑器，而是一个具备完整语法感知、代码导航、静态类型检查与单键执行能力的轻量级 Python 开发环境。在后续开发过程中，只需按照规范将新的代码文件组织在该项目文件夹下，即可始终享有稳定一致的开发体验。