简介面向Python初学者的VSCode运行入门教程重点解决在VSCode中配置Python环境并成功运行脚本的常见问题。资源为单个docx文档体积仅303KB内容以清晰的分步说明组织并配有操作位置提示便于快速查阅。文档覆盖从环境安装到实际运行的完整链路先安装Python与VSCode再通过扩展视图安装官方Python扩展随后创建Python文件并写入示例代码最后在窗口右下角选择解释器通过右键或运行按钮执行脚本。每一步均配有操作示意与输出演示例如print(Hello GeeksforGeeks)的终端效果可帮助读者直观确认每一步是否成功避免因环境配置不当而卡壳。目前已有534人学习使用尤其适合零基础学习者或刚接触VSCode的开发者按文档步骤操作即可避开常见坑点在几分钟内完成首次Python程序运行快速进入后续开发。1. VSCODE 跑 Python 文件装完环境还报错的问题多半不在代码很多从 PyCharm 转过来的人在 VSCODE 里的第一反应是我也装了 Python 扩展为什么点了右上角的运行按钮终端里要么报No module named numpy要么直接提示“未选择解释器”这个标题看着只是“运行一个 Python 文件”背后实际牵扯到解释器选择、扩展安装、终端执行、调试器配置一整套链路。这篇文章沿着这条路走一遍从装解释器开始到跑通第一行代码再到调试和虚拟环境顺手把最容易翻车的一批坑写清楚。适合刚开始用 VSCODE 写 Python 的开发者也适合从其他 IDE 转过来、想弄明白运行按钮背后逻辑的人。2. 先把地基打对Python 解释器、VSCODE 扩展与终端编码的安装选型2.1 解释器装哪个官网版、Miniconda 还是 Windows 商店版先说我自己的偏好只写脚本和工程代码直接去 python.org 下载最新稳定版做数据分析和机器学习装 Miniconda 更省事Windows 商店版和系统预装版本都不推荐作为主力。解释器是整个运行链路上最先要定下来的东西VSCODE 所有的运行、调试、装包行为最终都会落到一个具体解释器上装错后面全是连锁反应。方案适合场景要注意的事python.org 官网安装包通用开发安装时务必勾选 Add python.exe to PATHMiniconda / Anaconda数据分析和机器学习安装时选 Just Me不勾 Add to PATH 可减少终端干扰Windows 商店版临时验证有执行别名冲突python命令容易弹商店macOS / Linux 系统自带写系统脚本不要乱动系统 Python换版本建议用 pyenv 或 PPA安装完先别打开 VSCODE先验证解释器本身是好的。Windows 下打开 PowerShell 或命令提示符运行python --version python -c import sys; print(sys.executable)python -c是让解释器直接执行后面的字符串代码。这里做的事是打印 Python 可执行文件的绝对路径它决定了所有通过python命令启动的脚本和 pip 最终落在哪个环境。验证的目的不是看版本号而是确认终端里的 python 到底指向谁。Windows 上还有一条更重要的检查py -3 --version where pythonwhere python会把 PATH 里命中的 python.exe 全部列出来。如果第一行输出指向C:\Users\xxx\AppData\Local\Microsoft\WindowsApps说明你命中的是商店的占位别名不是真实解释器。我见过太多次这种情况命令行python --version显示 3.12但 VSCODE 运行按钮一直提示找不到解释器其实就是 PATH 里排在前面的python指向了 WindowsApps 的假入口。py -3是 Windows 自带的 Python 启动器按主版本号去调真实安装的解释器用它检查能绕开大部分 PATH 问题。装好解释器后把它丢到一边接下来配 VSCODE 一侧。2.2 核心插件只有一个ms-python.python别急着装 Code RunnerVSCODE 里跑 Python 的核心扩展只有一个Python发布者是 MicrosoftID 是ms-python.python。它负责识别 .py 文件、提供智能提示、集成 Pylance 语言服务器、激活运行按钮和调试器。装完 Python 扩展后VSCODE 会提示你装 Pylance一并确认即可。不习惯在扩展面板里搜索的话也可以在终端里直接执行code --install-extension ms-python.python code --install-extension ms-python.vscode-pylance如果提示code命令不存在需要在 VSCODE 里按CtrlShiftP执行 “Shell Command: Install code command in PATH”然后重开终端。这个操作经常被忽略code命令是 VSCODE 自己的命令行工具安装 VSCODE 时不会自动放进 PATH。Code Runner 很多人喜欢装但我不首推。它能在不配置解释器的情况下把 Python 脚本跑起来问题是它默认用code-runner.executorMap里写死的命令去执行你换了 conda 环境或虚拟环境后它还是只认写死的那个 python。等你后面用调试器、用运行按钮发现两边结果不一致排查起来非常难受。新手期就只用官方 Python 扩展跑通之后再按需补。装完扩展后状态栏右下角会出现当前解释器名称。Python 扩展装好后会自动激活你打开一个 .py 文件它会尝试扫描环境里可用的解释器扫描阶段右上角运行按钮可能是灰的等一两秒刷新完才会亮。2.3 终端编码Windows 下第一次跑 Python 就乱码先把代码页理顺在 Windows 上VSCODE 集成终端的默认代码页可能是 GBK代码页 936而 Python 3 的源码默认是 UTF-8。print(你好)输出中文时终端解码错乱就会出现乱码程序里用open()读一个 UTF-8 的文本文件且没指定编码还会抛UnicodeDecodeError: gbk codec cant decode。终端层面的临时处理chcp 65001 python app.pychcp 65001把当前终端窗口的代码页切成 UTF-8。注意这个操作是临时的关掉终端再开就恢复所以只适合快速验证。想固化可以在 VSCODE 的设置里配置终端默认参数或者干脆在代码层面绕开。代码层面最稳的做法是读写文件时显式指定编码with open(data.txt, r, encodingutf-8) as f: text f.read()open()的encoding参数在 Python 3 里默认取 locale 编码中文 Windows 上就是 gbk。显式传encodingutf-8后程序在 Windows、macOS、Linux 上的行为一致这是跨平台脚本里最值得养成的一个习惯。还有一个全局开关环境变量里设置PYTHONUTF81或者在命令行用python -X utf8 app.py启动让 Python 进入 UTF-8 模式。这个模式会把 stdin、stdout、默认文件编码全部切到 UTF-8。不过它是全局生效的如果你只处理某个具体文件优先在代码里显式指定编码不要全局改。3. 用运行按钮跑通第一个文件解释器选择与运行逻辑3.1 新建项目、选对解释器再点那个三角按钮以最简单的方式开始新建一个文件夹在 VSCODE 里 File Open Folder 打开它新建app.py写一个打印脚本。最关键的第一步是在状态栏右下角点击 Python 版本号或者按CtrlShiftP输入 “Python: Select Interpreter”在弹出的列表里选一个可用的解释器。import sys print(sys.executable) print(hello from vscode)这个小脚本的用途是验证print(sys.executable)输出的路径就是后续所有运行、调试、装包时真正生效的解释器。如果你选了 A 环境而依赖装在了 B 环境运行按钮自然报ModuleNotFoundError这跟代码本身没关系。选完解释器后右上角的三角按钮会变成可用状态。点击它或者在 .py 文件里右键选择 “Run Python File in Terminal”VSCODE 会在下方打开集成终端终端里出现的执行命令大致长这样 D:/code/test-project/.venv/Scripts/python.exe D:/code/test-project/app.py注意这里有个很多人没意识到的细节VSCODE 并不是先激活你的虚拟环境再去敲python app.py而是直接调用了当前选定解释器的绝对路径。所以哪怕你的终端当前处在完全未激活的状态运行按钮也能用对解释器。这也是它比手动敲命令更“稳”的原因。3.2 运行按钮的逻辑它只认状态栏里选定的解释器上一节看到的执行命令解释了运行按钮的本质把“当前选定的解释器路径”和“当前打开的 .py 文件路径”拼成一条完整的执行语句丢到集成终端里跑。它不依赖你手动激活任何环境也不读系统 PATH 里的 python 命令。这个设计直接回答了一个高频困惑“我在 VSCODE 里跑得好好的自己在终端里敲python xxx.py却报错”。因为你自己开终端时终端用的是 PATH 里那个 Python不一定是 VSCODE 状态栏里选的那个。尤其是 conda 用户最容易踩VSCODE 里选了conda activate base的环境运行按钮正常自己在 PowerShell 里敲python用的却是系统全局 Python依赖对不上。所以如果你打算在终端里手动跑脚本就应该主动做好两步先确认当前终端用的是哪个解释器再执行代码。手动跑之前可以加一句python -c import sys; print(sys.executable)输出路径和 VSCODE 状态栏显示的一致再跑正文不一致就先CtrlShiftP重新选解释器。养成这个习惯之后能省下一大半环境类报错的排查时间。3.3 运行按钮传不了参数想要命令行参数走调试器运行按钮做得简单代价是不提供参数入口。你想给脚本传--input data.csv、--epochs 100这样的参数点击运行按钮是传不进去的只能在代码里临时写死或者走调试器。常见做法是在项目根目录建.vscode/launch.json写一个调试配置把参数通过args字段传进去{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, args: [--input, data.csv, --epochs, 10], justMyCode: true } ] }然后按F5启动脚本里通过sys.argv拿到这些参数import sys print(sys.argv[1:])几个字段值得说清楚type现在必须是debugpy网上老教程里写的type: python已经过时了program是程序入口${file}是 VSCODE 内置变量代表当前打开的文件args里每个引号是一个独立参数不需要自己拼字符串VSCODE 会按数组逐个传justMyCode控制调试时是否跳过第三方库代码设成false后可以 Step Into 进入 site-packages 内部正常排自己的逻辑保持true即可。第一次按 F5 时如果项目里还没有launch.jsonVSCODE 会弹出调试配置模板选 “Python Debugger” 就能自动生成不需要手动从零写。这也是我比较推荐新人的入口配置由编辑器生成自己再往args里补参数。4. 在集成终端手动运行与配置调试器从能跑到能排错4.1 集成终端里跑 Pythonpython 和 python -m 的差别有些场景下运行按钮反而不方便你要先跑一串别的命令再启动脚本或者想临时起一个文件服务。这时直接用 Ctrl 打开集成终端手动执行更有掌控感。最常用的几个命令及含义python app.py # 直接运行脚本文件 python -m pip install numpy # 用当前解释器的 pip 安装库 python -m http.server 8000 # 用当前环境起一个临时静态文件服务 python -m venv .venv # 创建虚拟环境python -m的含义是“把后面这个参数当模块来执行”它会优先在当前解释器的sys.path里搜索这个模块。这里有一个非常典型的场景很多人直接敲pip install numpy装包装完在 VSCODE 里import numpy还是报找不到模块原因就是pip命令属于全局 Python而 VSCODE 选的是 venv 解释器。换成python -m pip install numpy之后装包目标强制绑定了当前解释器这个问题从根源上消失。python -m http.server 8000是另一个常用招数临时把一个目录变成 HTTP 服务方便本地调试前端页面或者传输文件。注意运行按钮是做不了这种事的它只会执行当前 .py 文件这就是手动终端和运行按钮各自的边界。4.2 调试器配置launch.json 里几个决定行为差异的字段调试器的优势是能设断点、看变量、单步执行。按下 F9 在行号左侧点一下设置断点按下 F5 启动调试器程序停在第一个断点后左侧的“运行和调试”面板会显示局部变量、监视表达式和调用堆栈。launch.json里的字段看着多真正会改变行为的就几个{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, args: [], cwd: ${fileDirname}, env: { PYTHONPATH: ${workspaceFolder}/src, MY_FLAG: 1 }, justMyCode: true } ] }program用${file}适合单文件调试但工程里我更建议改成项目入口比如${workspaceFolder}/src/main.py。否则调试过程中你切到另一个 .py 文件再按 F5调试的就不再是刚才的入口了这个行为经常让人疑惑。cwd是“当前工作目录”它直接影响脚本里所有相对路径的解析。比如项目根目录下有data/文件夹入口文件在src/下脚本里写open(data/a.csv)如果 cwd 是${workspaceFolder}路径解析到的是项目根/data/a.csv没问题如果 cwd 没配默认继承终端的工作目录相对路径就跟着终端走了最容易翻车的点就在这里。我一般习惯写${fileDirname}意思是“当前文件所在目录”这样相对路径始终跟着脚本走。env字段用于在调试启动时注入环境变量不改代码就能临时设置密钥和开关。上面配置里的PYTHONPATH${workspaceFolder}/src是常见用法项目里不装包想让import server直接生效就靠这个字段把自己项目的 src 目录加到模块搜索路径里。4.3 用 tasks.json 绑定快捷键一键跑脚本调试器虽好日常快速验证一个脚本时反而有点重。我一般会为高频执行的动作配一个 tasks.json再绑一个顺手的快捷键。项目根目录的.vscode/tasks.json{ version: 2.0.0, tasks: [ { label: run-current-file, type: shell, command: python, args: [${file}], options: { cwd: ${fileDirname} }, presentation: { reveal: always, panel: dedicated }, problemMatcher: [] } ] }这段配置里最关键的是options.cwd。它把终端工作目录切到当前文件所在目录这样脚本里的相对路径不会因为你在项目其他目录打开终端而飘掉。problemMatcher留空数组是告诉 VSCODE 不需要解析编译错误因为 Python 的语法问题由 Pylance 在编辑器里直接标红不需要任务系统管。配好后按CtrlShiftP输入 “Tasks: Run Task”选run-current-file就能执行。想要更快在.vscode/keybindings.json里加一段{ key: ctrlaltr, command: workbench.action.tasks.runTask, args: run-current-file }之后按CtrlAltR直接跑当前文件省去打开命令面板的步骤。这个方式适合参数写死在脚本里、不需要交互输入的批处理脚本比调试器轻比运行按钮灵活。5. 避坑VSCODE 跑 Python 的 5 个高频踩坑现场5.1 终端里输入 python 弹出微软商店现象在 VSCODE 集成终端或命令行里执行python --version不是输出版本号而是打开了 Microsoft Store 的 Python 下载页面。原因本机装了 Python 但安装目录没进 PATH或者安装时漏勾了 Add python.exe to PATH。Windows 的“应用程序执行别名”功能提供了一个虚设的 python.exe 占位符它在 PATH 中排在真实 Python 前面于是敲 python 就弹商店。解决打开 设置 应用 高级应用设置 应用执行别名把 python.exe 和 python3.exe 两个开关关掉然后重开终端。如果还不行执行where python看第一条路径如果是 WindowsApps去环境变量里把真实 Python 安装目录移到 PATH 靠前位置。顺手把C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\和同目录下的Scripts都加进去pip 命令也会一起恢复。另外 Windows 下始终可以用py -3绕开这个坑它不依赖 PATH直接按版本号找解释器。5.2 运行按钮报 ModuleNotFoundError但 PyCharm 里能跑现象VSCODE 里点运行按钮控制台抛ModuleNotFoundError: No module named numpy同一个项目在 PyCharm 里运行正常。原因VSCODE 运行按钮直接调用状态栏选定的解释器如果你项目用了一个 venv而 VSCODE 里还选着全局 Python它就拿全局 Python 去执行代码。项目里装的依赖在 venv 的 site-packages 里全局自然 import 不到。PyCharm 会为每个项目自动建好解释器关联所以你感觉不到这个问题。解决按CtrlShiftP执行 Python: Select Interpreter在下拉列表里换成项目对应的解释器然后重跑。更稳妥的验证方式是先在集成终端跑一次python -c import sys; print(sys.executable)看打印出的路径是否指向项目 venv不一致就回到 VSCODE 状态栏重新选择。注意手动在终端conda activate xxx不会影响运行按钮它俩互不干涉必须在选择器里改才算数。5.3 读文件报 UnicodeDecodeError: gbk codec cant decode现象代码里用open(data.txt)读取一个 UTF-8 编码的文本文件在 Windows 上抛UnicodeDecodeError在 macOS 或 Linux 上完全正常。原因open()未指定 encoding 时Python 3 默认使用当前 locale 的编码。中文 Windows 的默认编码是 GBK也就是 cp936传入 UTF-8 字节流自然解码失败。VSCODE 编辑器里看着内容是正常的因为编辑器默认编码是 UTF-8这和解释器的默认解码编码完全是两回事。解决读文件时显式传encoding参数这是最稳的修复with open(data.txt, r, encodingutf-8) as f: data f.read()同时建议把项目里所有源文件和文本文件统一存成 UTF-8VSCODE 右下角状态栏点击当前文件编码选择 Save with Encoding UTF-8。团队里有 Windows 成员时文本文件统一 UTF-8能避免一半以上的乱码问题。如果只是本机脚本不想改代码设PYTHONUTF81环境变量也可以但它是全局生效的要考虑是否会影响其他依赖 GBK 编码的程序。5.4 launch.json 里写 pythonPath 报错或者已被移除现象从网上复制的 launch.json 里带着pythonPath: xxx在 VSCODE 里打开后报“未知的配置属性”或者按 F5 调试时报 pythonPath 已过期。原因VSCODE Python 扩展从 2023 年起把调试器迁移到了 DebugpypythonPath配置字段被移除。网上大量老教程没有及时更新复制过来直接踩坑。解决不要在 launch.json 里写解释器路径。调试配置默认沿用状态栏选定的解释器只要写 name、type、request、program 就能跑。如果确实要在配置里显式固定解释器新字段是python值写${command:python.interpreterPath}意思是运行时取当前选定的解释器路径。更省心的做法是直接删掉项目的 launch.json按 F5 让 VSCODE 重新生成一份全新模板再往里面补 args、cwd 之类的字段。5.5 打开项目后运行按钮是灰的F5 也没有反应现象新打开一个文件夹已装 Python 扩展右上角运行按钮灰色不可点按 F5 也没有任何反应。原因最常见的是 VSCODE 的安全特性——工作区信任。新打开项目时 VSCODE 会以受限模式运行Python 扩展的激活、运行按钮、调试器都会被禁用。其次如果文件夹里没有任何 .py 文件Python 扩展不会被激活按钮同样不亮。解决看窗口底部状态栏有没有“限制模式”横幅点“信任”或者执行命令面板 Workspaces: Manage Workspace Trust选择信任当前文件夹然后重载窗口。如果你是通过 WSL 或远程主机打开的项目还需确保对应的 Remote 扩展已安装并且 Python 扩展装在了远程侧Python 扩展装在本地 Windows 上是管不到 WSL 里的解释器的。6. 进阶用虚拟环境和项目级配置把“能跑”变成“稳定跑”6.1 用 venv 隔离项目VSCODE 会自动识别新建项目后第一件事就是建一个虚拟环境python -m venv .venvVSCODE 打开项目后如果检测到根目录下有.venv文件夹在选择解释器时会在列表里直接显示它并标注venv选完之后运行按钮就会自动用这个环境里的 Python。Windows 下如果 PowerShell 禁止执行激活脚本执行一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser即可。6.2 项目级 settings.json固定解释器、编码和检查模式在项目.vscode/settings.json里写{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/Scripts/python.exe, python.terminal.activateEnvironment: true, files.encoding: utf8, python.analysis.typeCheckingMode: basic }Windows 下虚拟环境解释器路径是.venv/Scripts/python.exemacOS 和 Linux 下是.venv/bin/python。用${workspaceFolder}开头保证团队里每个人打开这个项目时默认都指向项目自己的解释器不会误用全局 Python。typeCheckingMode设成basic后Pylance 会对明显的类型错误给出提示又不会像 strict 模式那样到处标红是个平衡点。说一说我自己的习惯每次新项目先建.venv再选解释器最后敲第一行代码。有几次偷懒没建虚拟环境直接 pip install依赖全装进全局后面换机器或者升级 Python 版本时才想起来后悔。VSCODE 的运行按钮只管“运行”不管“依赖装在哪”所以规范化的第一步应该从环境开始。希望这篇文章能帮你把这一步走稳少踩我踩过的这些坑也希望能让 VSCODE 真正成为你顺手、可信赖的 Python 开发工具。本文还有配套的精品资源点击获取