很多刚入门 Python 的朋友，还有不少从 PyCharm 转过来的老开发，都问过我同一个问题：VS Code 到底怎么配才能舒服地写 Python？这个问题网上答案一堆，但要么只讲了个皮毛，要么就是版本太老，照着做根本跑不起来。我过去几年一直拿 VS Code 当主力写 Python，从简单的脚本到 FastAPI 服务都在这上面跑，中间踩过的坑不少，但也确实摸出了一套比较顺手的配置组合。今天就把这套完整的东西整理出来，从零开始，一步步来，保证你看完能直接上手。
这篇文章适合谁？纯新手，之前没配过 Python 环境的小白；也适合已经在用 PyCharm，但想体验一下 VS Code 这种轻量编辑器写 Python 的人。内容覆盖 Python 本体安装、VS Code 安装、解释器选择、调试器配置、虚拟环境、代码格式化、Git 集成等日常开发高频用到的环节。文章里的每一个步骤都是我实际验证过的，版本信息会标注清楚，避免你照着旧教程配完发现界面都对不上。
1. 为什么在 VS Code 里写 Python，而不是用 PyCharm
先聊点选型上的事。很多人一开始纠结：VS Code 和 PyCharm 到底选哪个？我的看法是，如果你主要写 Python，并且愿意接受一点初始配置成本，VS Code 的灵活性和资源占用会让你很舒服；如果你需要开箱即用的重型 IDE，那 PyCharm 的社区版也能满足大部分需求。以下是我长期使用 VS Code 写 Python 后，觉得它最突出的几个点。
1.1 轻量启动、全栈通用，生态整合度更高
PyCharm 打开一个项目时，索引构建阶段会明显卡顿，项目一大，内存占用轻松破 2GB。VS Code 本身就是编辑器，启动速度非常快，虽然加载 Python 插件后也会占用资源，但整体体感轻很多。而且 VS Code 不仅是 Python，你还能在里面写 JavaScript、Go、Rust、SQL，甚至直接用 Remote-SSH 连接服务器开发，不需要在多个 IDE 之间切换。
再加上 VS Code 自带一个非常完整的扩展市场，微软官方提供的 Python 扩展包（包含 Pylance、Jupyter、Debugger 等功能）更新极其频繁，Python 新版本出来后几乎一两天内就能适配。这意味着你不需要等大版本升级，就能用到对新语法的支持。
1.2 VS Code 配置 Python 的整体流程是什么样的
从一个干净的电脑到能跑通第一个脚本，其实只有下面几条主线。掌握这个框架，你在任何机器上重配环境都不会慌。
- 安装 Python 解释器本体（从官网或包管理器安装，并确保 PATH 正确）。
- 安装 VS Code 编辑器本体。
- 在 VS Code 的扩展市场安装 Python 相关扩展（中文语言包可选但有帮助）。
- 在 VS Code 中选择正确的 Python 解释器。
- 新建
.py文件并运行，验证环境。 - 按需配置调试、代码检查、格式化、虚拟环境等进阶项。
这条链路是固定的，很多人配置失败，往往是在第一环或者第四环出了问题。接下来的章节，我就按这个顺序把所有细节拆开，每一步讲清楚为什么要这么做。
2. Python 与 VS Code 安装准备：先把地基打牢
很多教程上来就让装 VS Code 插件，但解释器没配好，装了插件照样报错。这一步虽然基础，但它的重要性不亚于后面的所有配置。
2.1 Python 解释器安装的 3 个关键细节
Python 安装本身看起来没什么技术含量，双击下一步就行，但这里有几个关键点直接影响 VS Code 能不能识别到它。
第一个关键点：千万别忘记勾选 "Add Python to PATH"。下载安装包后，运行安装程序，在第一个界面最下方有一条 "Add Python 3.x to PATH" 的复选框，默认是没勾选的。很多人直接点了 Install Now，装完才发现命令提示符里输入python没有反应。这个选项的作用是把 Python 的可执行文件路径自动写入系统环境变量，VS Code 依赖这个环境变量来定位解释器。如果没勾，麻烦不小。
我建议的安装方式：勾选 Add Python to PATH，然后点 Install Now。如果是 Windows 11 或 Windows 10 系统，强烈建议选择 "Install Now" 上面的 "Customize installation" 选项，把下一级页面里的 "Install for all users" 也勾上，避免某些路径权限问题导致后续无法写文件。
第二个关键点：版本选型。不要追求最新，优先选择当前生态兼容性最稳的版本。例如 2024 年到 2025 年初，Python 3.9 到 3.12 是大多数第三方库已经完美兼容的范围。如果你要用 TensorFlow 或某些旧版依赖，Python 3.12 可能会遇到兼容性问题，那退一步装 3.10 或 3.11 是更稳妥的选择。VS Code 本身对 Python 版本没有特殊要求，关键看你项目依赖。
第三个关键点：验证安装是否成功。安装完成后，打开新的命令提示符窗口（管理员身份不是必须的），输入：
python --version如果输出类似Python 3.12.4这样的字样，说明路径没问题。如果提示python 不是内部或外部命令，说明 PATH 没配上，需要手动去系统环境变量里检查或重新安装。
注意：安装完成后务必新开一个终端窗口再执行验证，不要在当前已打开的环境变量未刷新的窗口里测，否则即使装好了也可能报错。
2.2 安装 VS Code 及必要的初始化配置
VS Code 的下载比较直接，官网下载 Windows 版本的 User Installer 即可。安装过程中有几个选项值得花点心思。
安装到选择附加任务那一步时，有四件事建议你勾上：
- 勾选"添加到 PATH"——这样以后可以在任意终端直接输入
code .打开项目。 - 勾选"添加"到资源管理器"目录上下文菜单"——在文件夹上右键就能直接进入 VS Code 打开，效率很高。
- 勾选"添加到开始菜单""桌面快捷方式"这些按个人习惯。
- Windows 10 及以上系统，"在终端中运行 code 命令"这个选项非常关键。
安装完成后，打开 VS Code，第一件事是装中文语言包（如果你习惯英文界面可以跳过）。点击左侧工具栏的扩展图标（那个四个方块组成的按钮），搜索Chinese (Simplified) (简体中文) Language Pack，安装后右下角会提示重启。这个包只是界面汉化，不涉及 Python 功能的任何改动，完全可控。
接下来是 Python 扩展。直接在扩展市场搜索Python，认准发布者为Microsoft的扩展，安装那个。这个扩展现在已经自动捆绑了 Pylance、Python Debugger 两个子扩展，不需要分开找。
装完这两个之后，我建议顺手装一个Python Extension Pack，它是微软出的 Python 全家桶，包含 pytest、Jupyter、venv 自动识别等常用组件，一次性搞定后续很多功能。
2.3 用命令行方式初始化项目文件夹（可选但推荐）
VS Code 最好的使用习惯是一个项目一个文件夹。比如你想在D:\projects\python-learn下写代码，先在本地创建好这个文件夹，然后在 VS Code 的菜单栏选择"文件-打开文件夹"。也可以直接快捷操作：
在 Windows 终端中进入D:\projects\python-learn目录，输入：
code .这个命令会自动用 VS Code 打开当前目录。这个习惯非常好，因为 VS Code 的所有项目配置都保存在项目根目录下的.vscode文件夹里，以文件夹为单位管理项目，切换项目时配置互不干扰，这点后面调试配置时会体现出来。
3. VS Code 核心配置：让编辑器真正变成 Python IDE
前面装好了基础软件，这一步处理的是连接 VS Code 与 Python 解释器的关键环节。很多新手在这一步容易踩坑，因为 VS Code 不会自动找到解释器，必须手动指定一次。
3.1 选择正确的 Python 解释器：所有操作的前提
在你的项目文件夹中新建一个测试文件hello.py，随便写一行print("hello")。然后在 VS Code 界面按下快捷键Ctrl+Shift+P，输入 "Python: Select Interpreter"，回车。
弹出的列表中，VS Code 会自动扫描你系统里所有可用的 Python 环境。包括：
- 官方 Python 安装包安装的全局 Python
- Anaconda 或 Miniconda 创建的虚拟环境
- 用
python -m venv创建的项目虚拟环境（前提是已经存在）
选中你的目标解释器后，状态栏的右下角会显示类似 "Python 3.12.4" 的字样，说明 VS Code 已经和这个解释器打通了。
为什么要手动选择，而不是自动选择？因为一个系统里可能存在多个 Python 环境。比如你系统里装了 Python 3.11，同时又创建了一个 Python 3.10 的 venv，如果 VS Code 默认选了全局的 3.11，而你的项目依赖只在 3.10 里，运行时必然报 ModuleNotFoundError。手动指定这一步就是确保编辑器与执行环境的绑定一致。
提示：选择解释器后，VS Code 会在项目目录下生成
.vscode/settings.json文件，里面记录了解释器路径。后续如果换机器，删掉这个文件重新选即可。
3.2 配置代码检查与格式化：写代码的时候就知道对不对
选好解释器之后，VS Code 的 Python 扩展会自动提供基础的语法检查。但要达到"写一行报错一行"的爽感，还需要配置两个工具——代码检查和代码格式化。
以前常用的代码检查工具是 flake8，代码格式化工具是 black。不过到了 2025 年，团队更多优先用ruff。Ruff 是 Rust 写的 linter + formatter，速度极快，检查规则全面，而且配置极简。VS Code 的 Python 扩展已经内置了对 Ruff 的支持，我们只需要：
- 在终端安装 Ruff：
pip install ruff- 在 VS Code 设置里做两处调整：
打开设置方式：左下角齿轮-设置，或者直接按Ctrl+,。搜索python.linting.enabled，确认勾选。再搜索python.formatting.provider，在下拉框里选择ruff。
不过我更推荐直接改.vscode/settings.json文件，一劳永逸：
{ "python.linting.enabled": true, "python.linting.lintOnSave": true, "python.formatting.provider": "ruff", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.organizeImports": "explicit" }, "python.analysis.typeCheckingMode": "basic" }editor.formatOnSave设为 true 的意义是：每次按保存键代码自动重新格式化，不再需要手动调整缩进、引号样式、行尾空格。editor.codeActionsOnSave里的organizeImports会自动帮你将 import 排序并去重——这在项目文件变多以后非常实用。
这些配置保存后，再回去看hello.py，如果代码有不符合规范的地方，编辑器里会直接出现黄色波浪线。鼠标悬停，会看到具体的规则说明。
3.3 调试器配置：launch.json 的一步步解释
VS Code 里 Python 的调试功能极其重要，尤其是逐行断点调试。默认情况下，按F5调试一个简单的 Python 文件，VS Code 会自动使用默认调试配置。但要完全可控，最好手动创建调试配置。
点击左侧的运行和调试图标（那只虫子），点击"创建 launch.json 文件"，选择 "Python Debugger"，然后选择 "Python 文件"。生成的 launch.json 类似这样：
{ "version": "0.2.0", "configurations": [ { "name": "Python: 当前文件", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal" } ] }关键字段的含义说清楚：
name：显示在调试配置下拉框里的名称，可随意修改。type：调试器类型，固定为 debugpy。request：launch表示启动新进程调试，attach表示连接到已运行的进程。program：要调试的目标文件。${file}表示当前激活的文件。如果你想固定调试某个人口文件（比如项目里的main.py），就把它改成"${workspaceFolder}/main.py"。console：integratedTerminal表示程序输出显示在 VS Code 内部的终端里。选择externalTerminal则会弹出一个独立窗口，这在某些 GUI 程序调试时有意义。
配置完成后，在hello.py某一行代码左侧单击，出现红色圆点表示断点。按F5，程序会运行到断点处暂停，此时左侧面板可以查看所有变量的当前值，顶部有步过、步入、步出等操作按钮。这是排查逻辑错误最高效的方式。
3.4 集成终端与运行按钮：最常用的两个入口
VS Code 内置的终端功能非常方便。在菜单栏选择"终端-新建终端",或按Ctrl+`快捷键，底部会打开集成终端。这个终端默认会激活你当前选择的 Python 解释器所在的虚拟环境（如果你在 venv 里）。这里是执行pip install等命令行操作的主要位置。
另外，文件右上角有一个三角形运行按钮，点击它会直接用当前的 Python 解释器运行该文件，并输出内容到下方面板。很多新手点完发现没有弹出一个终端窗口，以为是 bug，其实输出就显示在下方的"输出"或"终端"面板里，注意查看标签页切换。
注意：在集成终端里执行
python xxx.py时，确保终端左侧显示的是你当前的项目目录，而不是某个其他目录。否则会出现"找不到指定模块"或"文件路径错误"的问题。可以用cd /d D:\projects\python-learn这种命令先切换目录。
4. 进阶配置与效率提升：日常开发效率翻倍的关键
到这里，基础的配置已经能让你舒服地写代码了。但要说"把这套环境打磨到顺手"，还差几个进阶项。这里每个功能都是我实际使用中感觉提升最明显的部分。
4.1 虚拟环境 venv 的创建与使用：为什么必须做
写 Python 项目时，最忌讳的是把所有依赖都装到全局环境里。不同项目可能用到相同包的不同版本，全局安装迟早会冲突。venv 就是 Python 官方的解决方案，它能在项目目录下创建一个独立的 Python 环境，所有安装的包都只对这个项目生效。
在 VS Code 集成终端里执行：
python -m venv venv这会在当前目录生成一个venv子目录。随后激活它：
- Windows PowerShell：
venv\Scripts\Activate.ps1 - Windows CMD：
venv\Scripts\activate.bat - macOS / Linux：
source venv/bin/activate
激活后，终端命令行最左侧会出现(venv)的前缀，表示你已经在虚拟环境里了。这时再执行pip install requests，安装的包只会进这个 venv，不会污染全局环境。
VS Code 对 venv 的识别是自动的。当你重新打开项目文件夹时，如果没有手动选解释器，VS Code 会优先推荐项目里的venv/Scripts/python.exe。你只需要在 Select Interpreter 列表中选 "推荐" 的那一项即可。这一步做到了，后续所有的包管理和代码运行都在这个干净的独立环境里，非常安全。
你可能会问：现有的项目没建过 venv，只剩个requirements.txt，怎么办？激活虚拟环境后，执行：
pip install -r requirements.txt所有依赖就会安装到这个虚拟环境里，之后运行就不会再提示缺包了。
经验：如果你用的是 Anaconda，可以用
conda create -n 项目名 python=3.12创建对应版本的环境，再在 VS Code 里选择对应的解释器路径。conda 和 venv 的机制类似，灵活度上 conda 在科学计算场景反而更方便，因为很多二进制包 conda 直接提供预编译版本。
4.2 代码片段与快捷操作：写代码也可以像搭积木
写 Python 时，反复敲if __name__ == "__main__":和def __init__(self):很烦。VS Code 支持用户自定义代码片段，简化重复键入。
按Ctrl+Shift+P，输入 "Configure User Snippets"，选择 Python，然后往打开的python.json里添加自己的简写。比如：
{ "Python Main Guard": { "prefix": "main", "body": [ "def main():", " ${1:pass}", "", "if __name__ == '__main__':", " main()", "" ], "description": "Insert main guard" } }保存后，在.py文件中输入main，然后按 Tab 或回车，就会自动补全这段标准主函数结构。这个功能能节省大量时间，而且你可以按自己团队的编码规范定制。
除了代码片段，VS Code 的"多光标编辑"是另一个被低估的功能。按住Alt键，然后鼠标点击多个位置，就能在多个位置同时输入。在重构大量重复代码时，这一步操作效率的提升是肉眼可见的。
4.3 Git 集成：在编辑器里完成代码版本管理
VS Code 自带 Git 支持，但需要本机先装好 Git。如果系统里还没有，建议先去 Git 官网下载对应系统版本的安装包，安装时默认选项一路下一步即可。安装完重启 VS Code，源代码管理图标会变成可用状态。
在项目文件夹里初始化仓库，可以打开集成终端执行：
git init git add . git commit -m "init project"然后所有改动都会出现在左侧"源代码管理"面板里。修改过的文件会有一个 "M" 标记，新增文件是 "U" 标记。你可以直接在这个面板里输入提交信息，点击"提交"按钮完成一次提交。相比命令行，可视化操作对新手更友好，而且 diff 对比界面非常直观——点击文件可以看到左右两栏的逐行差异，绿色是新增，红色是删除。
如果你用 GitHub 或 GitLab，可以在扩展市场安装对应官方扩展，也可以利用 VS Code 自带的"使用 GitHub 登录"功能，将远程仓库和本地绑定。日常"commit-push-pull"三个操作基本可以完全在编辑器里面完成，不用切到终端。
为什么要刻意强调 Git 和 VS Code 的结合？因为很多初学者一开始不重视版本管理，等代码改崩了又找不到之前的版本，只能靠手动备份不同的命名文件夹。VS Code 把 Git 操作集成到了图形界面，大大降低了版本管理的上手门槛。我个人的习惯是，每完成一个小功能点就 commit 一次，养成这个习惯后，代码出错回滚是一件非常轻松的事。
5. 常见问题与排查技巧实录
配置过程中最耗时间的往往不是按步骤操作，而是遇到错误时完全不知道从何入手。这里把我实际踩过、也被别人问过最多的几类问题整理出来，做成一个速查表。每一个都附上我的排查思路和解决方案。
5.1 运行代码时提示"No Python interpreter selected"或解释器列表为空
这是新手最常碰到的问题。原因通常是 VS Code 没有找到任何 Python 解释器。
排查顺序如下：
- 先在系统终端验证 Python 是否真的能运行：
python --version。不能运行就去重装 Python，并注意勾选 Add to PATH。 - 如果终端能运行但 VS Code 找不到，检查是否安装了微软的 Python 扩展。没装扩展的话，VS Code 本身不会知道 Python 解释器在哪。
- 如果装了扩展还是找不到，重启一次 VS Code，让环境变量刷新。Windows 下修改 PATH 后已打开的进程不会自动感知新环境变量，必须重启。
- 还是不行，就手动指定。按
Ctrl+Shift+P，输入Python: Select Interpreter，点"输入解释器路径"，直接浏览到python.exe所在位置。
5.2 中文乱码问题：终端输出中文全是乱码
这个问题很经典，尤其是 Windows 系统上。根本原因是编码不一致：Python 默认输出字符串到标准输出时按平台默认编码，Windows 控制台默认的是 GBK，而 VS Code 集成终端默认 UTF-8，两者不一致导致乱码。
最简单的解决办法：在 VS Code 设置里搜索terminal.integrated.profiles.windows，修改默认终端的参数。也可以用一种更直接的方法——在集成终端里执行：
chcp 65001这个命令把终端代码页切换为 UTF-8，乱码问题立刻解决。但是每次新开终端都要执行，稍微麻烦。推荐的方案是在 VS Code 的 settings.json 里配置终端默认编码：
{ "terminal.integrated.profiles.windows": { "PowerShell": { "source": "PowerShell", "env": { "PYTHONIOENCODING": "utf-8" } } }, "terminal.integrated.defaultProfile.windows": "PowerShell" }加上PYTHONIOENCODING=utf-8后，Python 输出编码就固定为 UTF-8 了。不过还要注意，如果你的代码文件开头没有声明编码，Python 3 默认按 UTF-8 读取源文件，所以源文件里的中文字符串没问题；问题只是出在输出到终端时的转码。
5.3 F5 调试不起作用或程序直接退出
调试时遇到不触发断点，通常有几种可能：
- 断点打在代码无法执行的路径上。比如你在一行函数定义上打断点，但程序里根本没有调用这个函数，自然永远不会命中断点。断点一定要打在会执行的代码行，比如函数内部的执行语句。
- 当前调试配置跑的不是这个文件。检查 launch.json 里的
"program": "${file}"，如果写死成某个固定文件路径，那按 F5 永远调试的是那个文件。改成${file}或者在调试配置下拉框里确认选择了"当前文件"。 - 多环境混用。比如集成终端激活的是 venv 环境，但 VS Code 左上角解释器选择的是全局环境。调试时所以设置和运行都是基于被选择的解释器的，确保这两处一致。
5.4 启用了 linting 但代码没有波浪线提示
有的人配置完 settings.json，代码写错却不出红波浪线，很容易怀疑自己是不是装错了工具。
其实原因往往很简单：VS Code 的python.linting.enabled需要在修改设置后重启一次才完全生效。另外，检查你是否安装了 flake8/pylint/ruff 这些工具。VS Code 只是调用这些工具，工具本身缺失就什么都不显示。
用这个命令安装 ruff 后重启：
pip install ruff如果装的还是没反应，打开"输出"面板（快捷键Ctrl+Shift+U），在下拉菜单里选 "Python" 或 "Ruff"，看具体的报错日志。这是排查所有 Python 扩展问题的最有力手段。不要只盯着编辑器界面，日志里的信息才是准确的故障原因。
经验：把所有配置写在项目级的
.vscode/settings.json里，而不是用户级的全局设置里。项目级配置跟代码仓库走，换团队、换电脑、换项目都能保持一致的开发环境。如果你在团队里，把这个文件提交到 Git，新成员拉下来代码后自动获得全部配置。
5.5 用 pip 安装包时遇到 SSL 报错或者下载缓慢
这个在 Windows 上比较常见，通常是网络环境导致的。解决方案也简单直接：改用国内镜像源。比如在终端执行：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple如果希望一劳永逸，可以修改 pip 的默认全局配置。在用户目录下创建或编辑pip.ini（Windows）或pip.conf（macOS/Linux），内容：
[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple trusted-host = pypi.tuna.tsinghua.edu.cn保存后，后续所有pip install都会自动走镜像源，速度提升非常显著。这个方法在很多企业内网环境下同样有效，只是把源地址换成公司的内部 PyPI 服务器即可。
收尾：两个值得坚持的配置习惯
说完了完整的配置流程，最后分享两个我实际开发中使用频率最高、也最容易被新手忽略的小习惯。
第一，每次新项目都要新建虚拟环境，并按上文配置项目级 settings.json。不要因为"就写两行测试代码"而忽略这一步。等你项目写大之后想要重构依赖关系，没有虚拟环境会非常头疼。
第二，全程用 VS Code 的调试器而不是 print 大法。很多从脚本写起的人习惯了用print看变量，但在复杂逻辑调试时，断点+变量监视器的信息密度远高于 print。VS Code 里按一下F5，配合左侧的变量面板，你能看出每次循环后变量如何变化，很多时候 bug 一眼就能找到，根本不需要在代码里插桩再删除桩。
VS Code 配 Python 这件事，真正花时间的不是安装过程，而是理解每一步配置背后的逻辑。环境变量、解释器、调试器、虚拟环境这几个概念搞清楚了，你在任何一台新电脑上都能十分钟内把环境重新拉起来。希望这篇文章能让你少走一些我当年走过的弯路。
