很多刚入门 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 界面按下快捷键CtrlShiftP输入 Python: Select Interpreter回车。弹出的列表中VS Code 会自动扫描你系统里所有可用的 Python 环境。包括官方 Python 安装包安装的全局 PythonAnaconda 或 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 的支持我们只需要在终端安装 Ruffpip 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。requestlaunch表示启动新进程调试attach表示连接到已运行的进程。program要调试的目标文件。${file}表示当前激活的文件。如果你想固定调试某个人口文件比如项目里的main.py就把它改成${workspaceFolder}/main.py。consoleintegratedTerminal表示程序输出显示在 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 PowerShellvenv\Scripts\Activate.ps1Windows CMDvenv\Scripts\activate.batmacOS / Linuxsource 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 项目名 python3.12创建对应版本的环境再在 VS Code 里选择对应的解释器路径。conda 和 venv 的机制类似灵活度上 conda 在科学计算场景反而更方便因为很多二进制包 conda 直接提供预编译版本。4.2 代码片段与快捷操作写代码也可以像搭积木写 Python 时反复敲if __name__ __main__:和def __init__(self):很烦。VS Code 支持用户自定义代码片段简化重复键入。按CtrlShiftP输入 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 后已打开的进程不会自动感知新环境变量必须重启。还是不行就手动指定。按CtrlShiftP输入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 }加上PYTHONIOENCODINGutf-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如果装的还是没反应打开输出面板快捷键CtrlShiftU在下拉菜单里选 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.iniWindows或pip.confmacOS/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 这件事真正花时间的不是安装过程而是理解每一步配置背后的逻辑。环境变量、解释器、调试器、虚拟环境这几个概念搞清楚了你在任何一台新电脑上都能十分钟内把环境重新拉起来。希望这篇文章能让你少走一些我当年走过的弯路。
很多刚入门 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 界面按下快捷键CtrlShiftP输入 Python: Select Interpreter回车。弹出的列表中VS Code 会自动扫描你系统里所有可用的 Python 环境。包括官方 Python 安装包安装的全局 PythonAnaconda 或 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 的支持我们只需要在终端安装 Ruffpip 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。requestlaunch表示启动新进程调试attach表示连接到已运行的进程。program要调试的目标文件。${file}表示当前激活的文件。如果你想固定调试某个人口文件比如项目里的main.py就把它改成${workspaceFolder}/main.py。consoleintegratedTerminal表示程序输出显示在 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 PowerShellvenv\Scripts\Activate.ps1Windows CMDvenv\Scripts\activate.batmacOS / Linuxsource 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 项目名 python3.12创建对应版本的环境再在 VS Code 里选择对应的解释器路径。conda 和 venv 的机制类似灵活度上 conda 在科学计算场景反而更方便因为很多二进制包 conda 直接提供预编译版本。4.2 代码片段与快捷操作写代码也可以像搭积木写 Python 时反复敲if __name__ __main__:和def __init__(self):很烦。VS Code 支持用户自定义代码片段简化重复键入。按CtrlShiftP输入 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 后已打开的进程不会自动感知新环境变量必须重启。还是不行就手动指定。按CtrlShiftP输入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 }加上PYTHONIOENCODINGutf-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如果装的还是没反应打开输出面板快捷键CtrlShiftU在下拉菜单里选 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.iniWindows或pip.confmacOS/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 这件事真正花时间的不是安装过程而是理解每一步配置背后的逻辑。环境变量、解释器、调试器、虚拟环境这几个概念搞清楚了你在任何一台新电脑上都能十分钟内把环境重新拉起来。希望这篇文章能让你少走一些我当年走过的弯路。
