VSCode中配置Python环境与运行Hello World的保姆级教程

1. 写在前面的几句话：为什么这类教程永远有市场

搞了这么多年技术，也带过不少刚入门的朋友，我发现一个很扎心的事实：真正劝退新手的，往往不是Python语法，也不是编程逻辑，而是 还没开始写代码，就死在环境配置上了 。下载Python时选错版本、安装时漏勾选路径、装完VSCode不知道装什么插件、写第一行print时终端直接乱码——随便哪一步，都能让一个满怀热情的新手原地崩溃。

这也是我写这篇教程的初衷。我不打算复述官网那种冷冰冰的“Next一路点到底”流程，而是把 每一步背后的原理、容易踩的坑、以及装完之后怎么验证 都讲透。看完这篇，你不仅能把Python和VSCode装起来，还能理解你刚才到底做了什么、为什么这么做，以后再遇到环境问题，也有能力自己排查。

这篇教程适合完全零基础的小白，也适合那些“装是装好了但总觉得哪里不对劲”的朋友。我会以Windows系统为主（毕竟大多数新手用的都是Windows），macOS的差异部分也会单独说明。

2. 先搞定Python本体：版本选择和下载阶段的坑

2.1 去官网下载时，别点错按钮

Python的官方下载地址是 python.org/downloads ，这一点没啥争议。但打开页面后，很多人会先看到一个大大的黄色按钮“Download Python 3.x.x”，下面还有一堆其他版本和文件列表。新手最容易犯的错误有两种：

第一种， 点成了其他平台的安装包 。比如你是Windows系统，却下载了“macOS 64-bit universal2 installer”或者源码包（Source code），装了半天发现打不开。Windows用户要认准带“Windows installer”字样的文件，通常在网页下方的文件列表里能找到，更稳妥的做法是打开下载页面后直接按 Ctrl+F 搜索“Windows installer (64-bit)”。

第二种， 下载了32位版本 。现在新电脑基本都是64位操作系统，但仍有一些第三方库对32位Python支持得不好。建议一律选择“Windows installer (64-bit)”。怎么看自己系统是不是64位？右键“此电脑”选“属性”，或者打开设置→系统→系统信息，就能查到。

2.2 到底选最新版还是稳定版

Python的版本更新非常勤，每年一个大版本，小版本也持续迭代。很多新手一看到3.13、3.12这种版本号就开始纠结：是不是越新越好？

我的建议是： 没有特殊需求的话，选当天官网首页推荐的最新稳定版即可 。但如果你后续要装TensorFlow、PyTorch这类重量级库，或者要用一些老项目，就要留意库是否已经适配新版本。这个时候，一个比较稳妥的思路是选择“次新版本”，比如最新是3.13，那选3.12通常兼容性更好。等装完VSCode再安装第三方包时如果报错“找不到对应版本”，回来的方向大概率就在Python版本上。

实测下来，Python 3.10、3.11、3.12目前对新手而言差别不大，选哪个都能顺利完成本教程。真正需要盯紧的是 位数（32/64）和安装包类型（installer/source） ，这俩错了才会出大问题。

2.3 安装时那个“Add Python to PATH”究竟有什么用

许多新手在Windows安装界面看到“Add Python to PATH”这个复选框，不明觉厉，甚至有的教程会告诉你“一定要勾”，但没说为什么。简单说， PATH是Windows用来查找可执行文件的环境变量列表 。

当你勾选了“Add Python to PATH”，安装程序会把Python的安装目录和它的Scripts子目录写进这个列表里。之后你在命令行输入 python 或 pip ，Windows就会自动去这些目录里找到对应的exe并运行。不勾选的话，安装完你在命令行里敲 python ，大概率提示“‘python’不是内部或外部命令”。

所以，正确操作是： 安装向导第一步就直接勾选“Add Python to PATH” ，然后点“Install Now”就可以。还有一个容易被忽略的选项是“Install for all users”，我建议也勾上，避免后面命令行权限问题。安装完成后如果界面出现“Setup was successful”，这一步就算过了，可以先不用管那个“Disable path length limit”提示，2.5小节再解释。

3. 安装完成不等于结束：验证安装和PATH的心智模型

3.1 一键安装完成后，先别急着打开VSCode

很多人装完Python就急吼吼地打开VSCode写代码，结果发现终端里 python 命令根本无效，于是怀疑安装失败了。其实大多数情况不是安装失败，而是 你根本还没进对地方验证 。

验证安装的第一步，是打开Windows的命令行工具。按 Win + R ，输入 cmd ，回车，就打开了传统的命令提示符。这时输入：

python --version

或者：

python -V

如果看到类似 Python 3.12.4 的输出，说明Python本体已经装好，并且PATH也生效了。如果提示“不是内部或外部命令”，先别慌，打开安装目录看一眼，确认 python.exe 确实存在。如果你确实勾选了Add to PATH但还是没生效，多半是安装向导后要重启一下终端，或者干脆重启电脑让环境变量刷新。

补充一个细节：有些Windows机器上，输入 python 会直接跳转打开微软商店（Microsoft Store），这是因为系统启用了“应用执行别名”功能。解决办法是打开“设置→应用→高级应用设置→应用执行别名”，把“应用安装程序 python.exe”和“python3.exe”这两个开关关掉。这算是一个非常隐蔽的小坑，很多人折腾半天找不到原因。

3.2 再验证一下pip，它是以后装库的大门

Python安装完成，自带的包管理工具pip也会一并装好。验证pip同样在命令行执行：

pip --version

正常会输出类似 pip 24.0 from C:\Python312\Lib\site-packages\pip (python 3.12) 的信息。如果你的 python 能用但 pip 提示找不到，也可以试试 python -m pip --version ，因为pip偶尔会因为环境变量配置不完整而无法直接调用，但通过 python -m pip 这种写法，等于明确告诉Python执行自己的模块，绕开了PATH的坑。这个技巧在后面装第三方库时非常实用，建议记下来。

到这里，Python本体这块就稳了。你其实已经成功了一大半，因为VSCode本身只是一个编辑器，真正的运行时是Python解释器，它现在已经在你的机器上待命了。

4. VSCode安装与必需的几个设置：编辑器选择不用纠结

4.1 官网下载时，认准User Installer还是System Installer

VSCode的下载页是 code.visualstudio.com ，注意别进了一堆仿冒站点。页面上一般有“.deb”“.rpm”“Windows”“macOS”等几个大图标，Windows用户直接点“Windows”下载即可。但下载下来的exe有64位和32位之分，同样建议选择64位版本。

VSCode官方的Windows安装包通常会有两个选项： User Installer 和 System Installer 。很多人不知道这有什么区别。简单说，User Installer安装在当前用户目录下，不需要管理员权限，适合个人使用；System Installer装在Program Files目录里，所有用户共享，但需要管理员权限。对新手来说两者都行，我个人建议选User Installer，因为后续更新更方便，也不太会碰到权限问题。

安装VSCode过程中，会有一个“选择附加任务”的界面，里面有几个复选框值得注意：

• “创建桌面快捷方式”看个人喜好。
• “将‘通过Code打开’操作添加到Windows资源管理器目录上下文菜单” 和 “将‘通过Code打开’操作添加到Windows资源管理器文件上下文菜单” ，建议勾上。勾选后你在任意文件夹上点右键，都能直接看到“通过Code打开”，进项目根目录超方便。
• 如果VSCode不是默认编辑器，也不需要勾“将Code注册为受支持文件的编辑器”。

4.2 第一个必须装的插件：Python

VSCode刚装完本质是个空壳编辑器，虽然内置对很多语言的基础支持，但Python开发必须靠扩展。打开VSCode左侧的“扩展”图标（五个方块形状），搜索“Python”，认准发布者为Microsoft的那个，作者是微软的官方插件，不要装错第三方的同名插件。装完之后记得点击“启用”或“激活”，最好再重启一下VSCode。

这个插件会联动Python解释器、代码补全、错误提示、调试器、Jupyter Notebook支持等一系列功能。很多人装完插件后说“还是没有代码提示”，原因其实不是插件问题，而是你还没有打开Python文件，或者VSCode没检测到解释器。后面4.4小节会讲怎么检查和选择解释器。

除了官方Python插件，我再推荐两个实用扩展：

• Pylance ：微软出的语言服务器，代码补全和类型提示能力大幅增强，也是官方推荐的。安装Python插件的时候大概率会自动带装，如果没有就手动搜一下安装。
• Python Debugger ：调试相关，首次配置launch.json时可能需要。新手前期用不上，可以先不管。

关于“要不要装一堆美化类、主题类插件”，我的态度是： 前期尽量少装 。每个人都经历过“装插件两小时，写代码五分钟”的阶段，插件装多了不仅拖慢启动速度，某些插件之间还有冲突，排查起来非常头疼。等真正用熟了，再按需添加。

4.3 安装简体中文界面？建议等一等

VSCode默认界面是英文的，不少新手一打开就发怵。官方有一个“Chinese (Simplified) (简体中文)”语言包插件，安装后右下角会提示重启并切换语言，照做就行。装上之后，菜单、设置、提示信息都会变成中文。

但我有一个不太一样的建议： 如果你以后打算长期干这行，尽量先别装中文包，至少在英文界面下用一段时间 。原因很简单，你以后查所有技术资料、复制报错信息、搜索答案，用的全是英文关键词，例如“Open Folder”“Terminal”“Run”这类。英文界面和资料对不上，反而会绕一大圈。当然，这只是个人经验，如果你看到英文就极度焦虑，先装中文包让自己能走下去，比任何建议都重要。等熟练后再卸载中文包也不迟。

4.4 指定Python解释器：VSCode里最重要的一步

现在Python有了、VSCode有了、Python插件也装好了，但VSCode还不知道该用哪个Python来运行你的代码。打开任意一个 .py 文件，你会看到VSCode右下角的状态栏显示着一个解释器版本号，比如“3.12.4 64-bit”。如果没显示，或者显示的是其他版本，就需要手动指定。

点击右下角的解释器版本号，或者按 Ctrl+Shift+P 打开命令面板，输入“Python: Select Interpreter”，弹出列表里会列出你机器上所有被检测到的Python。选择刚才装好的那个即可。这一步选错了，后续运行时会报错“没有配置解释器”或直接找不到模块，这是很多新手问“为什么我的代码不能运行”的根源。

这里额外提醒一个使用习惯： 建议直接在项目文件夹里创建 .py 文件，让VSCode打开的是整个文件夹，而不是单独打开一个文件 。操作方式：文件→打开文件夹，或者右键文件夹选择“通过Code打开”。这样VSCode才能正确识别项目结构，代码补全、调试、Git这些功能才会在完整上下文里工作。

5. 真正跑通Hello World：从终端到编辑器的全链路验证

5.1 三种运行方式，理解它们在干什么

Python写好后要怎么运行？大部分新手只知道VSCode右上角有个“▶运行”按钮，直接点，有时成功，有时报错。这里我把运行方式拆开讲一下，你们以后碰到的许多坑，是这三种方式混用导致的。

方式一：使用终端（Terminal）运行命令。 在VSCode里按 Ctrl+` 打开集成终端，此时终端里的路径应该已经自动定位到当前打开的文件夹目录。输入 python 文件名.py ，回车，就能看到输出。这个方式最直观，也最能帮助你理解“Python解释器执行了脚本文件”这件事。很多从PyCharm转过来的朋友初期不习惯，但掌握终端操作的收益是长期的。

方式二：VSCode右上角的“运行”三角按钮。 本质上是VSCode帮你找一个解释器，在集成终端中执行同样的 python 文件名.py 命令。方便是方便，但它依赖你在4.4里选择的解释器是否正确，如果选错，这里就会抛出奇怪的问题。

方式三：创建一个launch.json，用调试模式运行。 这个功能后边写复杂项目才用得上，新手阶段不必强制配置。确认代码能跑通后，你在“运行和调试”面板点“创建launch.json”，VSCode会自动生成一份配置文件，你可以把其中的“python”选成已安装的解释器路径。一般默认配置不用改就能用。

5.2 配置settings.json，让VSCode更顺手

VSCode本身支持海量个性化设置，最开始不用一下子全学，但有两项建议直接配好，是“保姆级教程”的必备操作。

用 Ctrl+Shift+P 打开命令面板，输入“Preferences: Open Settings (JSON)”，会打开一个叫 settings.json 的文件。把下面内容放进去：

{
  "python.defaultInterpreterPath": "C:\\Python312\\python.exe",
  "python.terminal.activateEnvironment": true,
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.python",
    "editor.formatOnType": true
  }
}

注意 python.defaultInterpreterPath 要替换成你机器上真实的Python安装路径。如果不知道具体路径，在命令行执行 where python （Windows）就能看到。配置完保存，VSCode再写代码时会给你自动格式化代码，比如代码末尾自动补分号、缩进统一等。这个习惯早期养成非常重要，Python是出了名的“缩进敏感”，格式不规范导致的报错占新手问题的很大一部分。

5.3 乱码问题：为什么print中文变成“锟斤拷”

新手运行第一段代码，十有八九会在中文输出时遇到编码问题。比如：

print("你好，世界")

在命令行里运行时可能显示正常，但在VSCode的集成终端里却变成乱码，甚至直接报错 SyntaxError: Non-UTF-8 code starting with '\xe4' 。

这个问题的根源是 编码不一致 。Python在读取源代码时默认使用UTF-8，但Windows终端的默认编码在中文环境下可能是GBK（也就是 cp936 ），两边的解码方式对不上，就出现了乱码。解决办法有几种：

把终端编码改成UTF-8 。在VSCode设置里搜索“terminal.integrated.profiles.windows”，给PowerShell或cmd配置 "args": ["/K", "chcp 65001"] ，这条命令把终端代码页改成UTF-8。也可以写一个“cmd /K chcp 65001”的Profile专门用来运行Python。

在代码文件最顶部加一行注释 ：

# -*- coding: utf-8 -*-

虽然Python3默认就是UTF-8，但显示乱码时加上这行，常常能稳定解决一部分老旧终端的问题。严格说不该依赖这个，但对新手是快速可用的技巧。

输出英文或数字测试 。先确认代码逻辑没问题，再去处理编码问题，每次只改一个变量，排查效率最高。

VSCode里还有一个“重新打开Editor with Encoding”的选项，在右下角状态栏那个编码名（如UTF-8）上点一下，可以用来强制指定当前文件的编码展示方式，排查编码导致的乱码很有用。

5.4 用一个完整小案例，走通全链路

理论说完了，我们实操一次。以下步骤你完全可以照着敲：

1.在电脑上建一个文件夹，命名为 python_study 。

2.打开VSCode，通过“文件→打开文件夹”打开这个文件夹。

3.Ctrl+Shift+P  输入“Python: Select Interpreter”，选刚才安装的3.x版本。

4.在左侧资源管理器面板中，点击“新建文件”，命名为 hello.py 。

5.写入代码：

import sys
print("Python 版本：", sys.version)
name = input("请输入你的名字：")
print("你好，", name)
print("Hello, World!")

6.按 Ctrl+` 打开集成终端，执行：

python hello.py

如果一切正常，你会先看到Python的版本信息，然后终端等待你输入名字，回车后输出问候语和Hello World。走到这一步，说明你的Python、VSCode、终端、解释器选择、编码配置全部打通了。接下来可以放心学基础语法。

6. 收尾之前的几个真实经验：关于Anaconda、虚拟环境和一个最容易被忽略的坑

6.1 为什么不建议新手一上来就装Anaconda

最近的热搜词里Anaconda和Miniconda出现频率很高，也有不少人问我：“我是不是要装Anaconda，因为它自带一堆包？”我的回答通常分两种：如果你只是学Python基础语法、写点脚本， 完全不需要Anaconda 。它自带几百个库，同时体积巨大，还会改掉你的PATH默认Python指向，后续等你真正理解了“环境”这个概念，再切换也不迟。

如果你的课程、教材明确要求用Anaconda，或者你是搞数据分析、机器学习方向，那更适合装Miniconda而不是完整版Anaconda。Miniconda只包含conda和Python，需要什么包再手动安装，干净、可控。到时候创建虚拟环境，conda的“环境隔离”思想能让你在多项目多版本中游刃有余。新手阶段，正常装一个官方Python足够起步了。

6.2 虚拟环境：从第一天就该养成的习惯

等你写了好几个小项目，就会发现“全局环境下pip install装了一堆包”会带来两个问题：一个是混乱，忘记哪些包属于哪个项目；另一个是冲突，比如A项目需要 numpy==1.21 ，B项目需要 numpy==1.26 ，装来装去就把环境搞坏了。

VSCode内建支持虚拟环境，给你一个最基础的做法（以Windows为例）。先在项目文件夹里打开集成终端，执行：

python -m venv venv

这会在当前文件夹下创建一个名为 venv 的虚拟环境，里面包含独立的Python解释器和pip。然后在同目录下执行：

venv\Scripts\activate

你会看到命令行前面多了一个 (venv) 前缀，说明虚拟环境已经激活了。此时再用 pip install 安装任何包，都会装进这个项目自己的“小空间”里，和全局环境互不干扰。之后在VSCode里按 Ctrl+Shift+P 选择解释器，就会看到 .venv\Scripts\python.exe 这个选项，选它即可。以后打开这个项目，VSCode会自动识别虚拟环境并激活。

6.3 装完还要注意什么：pip默认源、升级Python和常见报错

国内从pip官方源下载包经常很慢或直接超时，实在没必要硬扛。最简单的做法是临时指定国内镜像源。比如装 requests 这个库，可以执行：

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

也可以用 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple 永久更换默认源。换了之后下载速度会有质的飞跃。

另一个高频困扰是：“我明明升级了Python，VSCode还是旧版本”。这是解释器没切换导致的，先确认你在VSCode右下角选的解释器路径是否是新的Python安装目录。多版本并存时， where python 在Windows上可以列出所有被PATH覆盖的python路径，顺序基本就是解析的优先顺序。如果旧版本的路径排在前面，新的 python 命令会执行旧版本，解决办法是调整环境变量Path顺序，或者在VSCode里直接选择新的解释器路径，双保险。

还有个新手常踩的坑是：运行时提示 ModuleNotFoundError: No module named 'xxx' ，但你明明用pip装过这个包。大概率是因为pip装进了全局环境，而你的VSCode解释器选的是虚拟环境，或者反过来。遇到这个报错，先不要怀疑安装步骤， 用 pip list 看包到底装在哪里，再用VSCode右下角切换解释器，试到包能import成功为止 。

7. 最后想说的话

写这篇文章的时候，我尽量把自己当年踩过的坑都翻出来讲了。选版本、勾Path、选解释器、处理乱码、用好虚拟环境……每一条都是新手最容易忽略但影响最大的事。如果你完全跟着做下来，现在的你应该已经有了一个非常干净、可用的Python开发环境，也知道了这些配置背后的逻辑。剩下的，就是打开VSCode，新建一个 .py 文件，开始敲第一行代码。遇到问题不要慌，报错信息粘贴到搜索引擎里，十有八九能找到答案。环境配置这条路，走通一次，以后就再也挡不住你了。

以上就是VSCode中配置Python环境与运行Hello World的保姆级教程的详细内容，更多关于VSCode配置Python环境的资料请关注脚本之家其它相关文章！