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环境的资料请关注代码网其它相关文章！