简介面向Python初学者的VSCode运行配置指南以Word文档形式呈现系统梳理在Visual Studio Code中从零开始运行Python文件的关键流程。内容围绕环境搭建与基础操作展开涵盖Python与VSCode安装、官方Python扩展安装、创建脚本文件、选择解释器以及右键菜单运行、播放按钮运行、终端指定路径等多种启动方式步骤清晰且配有说明适合刚接触Python或希望规范开发环境的新手参照使用。文档附带简单示例输出可帮助读者直观理解运行原理减少环境配置中的常见困惑。资源包共1个docx文件大小约303KB体积小巧便于离线阅读或打印学习。该资源已有534人学习内容实用聚焦能在短时间内帮助读者掌握VSCode中Python文件的基本运行流程为后续编程练习打下基础。1. 在 VSCODE 中运行 Python 文件先搞清楚你卡在哪一步先把场景摆出来你在 VSCODE 里写好了第一段 Python 代码点右上角的三角按钮等了半天编辑器下方弹出一行红字无法找到 Python 解释器。换成在终端里敲 python hello.py又被告知 python 不是内部或外部命令。这两句话是 Python 入门路上最常见的拦路虎也恰恰说明在 VSCODE 中运行 Python 文件并不是装个 VSCODE 就能跑的事——它涉及解释器路径、插件、工作区信任、运行配置、虚拟环境和路径解析六件事。下面按顺序拆开讲新手能从头跟到尾被各种奇怪报错折腾过的入门用户也能直接跳到第 5 章对照排查。2. 运行 Python 文件前的环境准备解释器、插件与工作区三大件很多人搜完 vscode 安装教程把编辑器装好打开 .py 文件就开始期待那个绿色三角按钮出现。结果按钮不出现或者出现了点了没反应。这不是 VSCODE 的问题而是运行 Python这个动作依赖三样东西同时就位本机装好的 Python 解释器、VSCODE 里的 Python 插件、以及一个被信任的工作区。2.1 先把 Python 装对安装包选择、PATH 勾选与版本验证Windows 是重灾区。从 Python 官网下载安装包装完一路 Next 很容易漏掉最关键的一步安装窗口里有一个 Add python.exe to PATH 的勾选框。这个勾决定你能不能直接在终端里敲 python 命令。没勾的话VSCODE 集成终端里运行文件时会直接报python 不是内部或外部命令。如果已经装完且没勾 PATH有两个补救办法。一是重新运行安装包选 Modify勾上这个选项再走一遍二是手动把 Python 安装目录和它的 Scripts 子目录加进系统环境变量。我一般推荐前者重装一次不到两分钟不容易把系统 PATH 改乱而且重装不会动你已装的第三方包。装完以后先在终端里验证解释器本身是好的python --version pip --version验证命令说明第一条打印当前默认 Python 的版本号第二条确认包管理器 pip 能被找到。两个都有输出说明解释器本体没毛病后面出问题就该往 VSCODE 侧找。如果 python 没反应但你的 Python 确实装了试试py --version——Windows 的 py 启动器经常被单独安装py -3 --version可以明确指定 Python 3。Linux 和 macOS 的情况不同Linux 发行版很多预装 Python 3 但命令叫 python3macOS 系统自带的老版本 Python 最好别碰。另装一份官方 Python或者用apt install python3 python3-pip、dnf install python3 python3-pip安装都行。如果你在 VSCODE 里通过 WSL 做开发判断标准不变只是终端变成了 WSL 里的 bash命令名按 Linux 那套来。最终判断标准只有一个你能用某条命令稳定打印出版本号就把它当成项目默认解释器。2.2 VSCODE 端三件套Python 插件、Code Runner 与工作区信任Python 插件是必须项。扩展市场搜 Python认准发布者是 Microsoft 的那个。它提供三样东西解释器选择、运行按钮和调试支持。没有它.py 文件在 VSCODE 里就是纯文本右上角不会有运行按钮F5 也不能启动调试。vscode 配置 python 环境的第一步几乎都是先装这个插件。Code Runner 是可选项。它提供右键Run Code和另一套运行按钮胜在灵活第 6 章会讲它的关键参数。但它和 Python 插件的运行行为不完全一致新手阶段建议只保留一个主运行方式避免混用后搞不清楚到底是谁在跑你的代码。工作区信任是个容易被忽略的开关。VSCODE 较新版本加入了工作区信任机制打开一个不在信任列表里的文件夹编辑器顶部会弹条幅问你是否信任此文件夹的作者。点不信任的话调试、任务运行、部分插件功能会被禁用表现就是一切运行入口全部失效。自己写的项目直接点信任即可这个机制主要防的是网上下载的未知代码一打开就自动执行不建议全局关闭。装完插件、信任了工作区还差最后一步选择解释器。按CtrlShiftP打开命令面板输入 Python: Select Interpreter从列表里选一个。列表里通常有系统 Python、Anaconda、虚拟环境等多个候选。选完以后底部状态栏右侧会显示当前解释器的路径和版本。提示状态栏右侧显示的解释器才是运行按钮和调试器真正使用的解释器你在终端里敲 python 用的可能完全是另一个。排查环境类报错时永远先确认这两处是不是同一个。3. 在 VSCODE 中运行 Python 文件的三种方式按钮、调试与终端环境就位之后运行本身有三条路右上角运行按钮、F5 调试、终端手动执行。它们执行同一份代码但工作目录、解释器来源、可用的调试能力都不一样。很多人在家能跑、换台机器就跑不起来本质是没搞清自己用的是哪条路。3.1 右上角运行按钮它到底帮你执行了什么点运行按钮VSCODE 的实际动作是在集成终端里调用当前选中的解释器执行当前打开的文件。以 Windows PowerShell 为例生成的命令长这样 C:/Users/你的用户名/AppData/Local/Programs/Python/Python39/python.exe c:/Users/你的用户名/Desktop/demo/hello.py这条命令的含义是 PowerShell 的调用运算符后面跟着解释器完整路径再后面是被运行文件的完整路径。注意中间没有任何 cd 操作——也就是说终端的工作目录是 VSCODE 打开项目时的工作区根目录而不是文件所在目录。这是第 4 章相对路径翻车的起点先记住这个事实。Python 插件有个设置项python.terminal.executeInFileDir默认 false。设为 true 后点运行按钮会自动把终端工作目录切到当前文件所在目录能解决一部分路径问题但它改变的是终端行为不是调试器行为——F5 调试依然按 launch.json 来所以别指望一个开关通吃。3.2 F5 调试运行launch.json 的最小配置与参数调试适合排查逻辑错误断点、变量监视、单步执行。第一次按 F5VSCODE 会引导你创建 launch.json。一个能跑通当前文件的最小配置如下{ version: 0.2.0, configurations: [ { name: Python 调试当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal } ] }参数逐项说明name 是调试配置的名字显示在调试面板的下拉列表里可以随便起type 写debugpy这是当前 Python 插件使用的调试器类型旧教程里写python新装环境一律用 debugpyrequest 固定写launch表示启动新进程来调试另一个取值attach用于附着到已在运行的进程日常开发用不到program 是要运行的程序${file}是 VSCODE 变量代表当前激活的文件如果想固定调试项目入口可以改成${workspaceFolder}/main.pyconsole 决定程序的标准输入输出去哪里integratedTerminal输出到集成终端保留完整交互internalConsole输出到调试控制台界面干净但不支持 input() 交互输入。实际项目中几乎总会用到另外两个参数args: [--epochs, 50], cwd: ${fileDirname}参数说明args是传给程序的命令行参数不写的话你在终端里跑python train.py --epochs 50和 F5 调试的行为就不同cwd是程序的工作目录。很多训练脚本用相对路径读数据如果你在终端跑的时候习惯 cd 到数据目录那调试时就必须把 cwd 指到同一个目录否则同样的代码两种运行方式结果不同排查起来非常迷惑。3.3 终端手动运行python、python3、py 三个命令的区别终端运行是最朴素也最可控的方式但命令怎么敲取决于操作系统命令常见可用的系统说明pythonWindows、部分 macOS指向 PATH 中第一个 Python受虚拟环境影响python3Linux、macOSLinux 发行版默认命令Windows 上通常不存在pyWindowspy 启动器py -3 main.py明确用 Python 3判断方法很简单三条命令挨个在终端敲一遍哪条能打印出版本号就用哪条。但这里有个老坑同一个终端里 python 指向谁取决于你有没有先激活虚拟环境。激活后python 是虚拟环境里的没激活python 是系统的。你要是先敲了pip install numpy再激活虚拟环境跑代码报 No module named 就一点也不冤。我个人的习惯Windows 上用 py 启动器进入项目后第一时间激活虚拟环境然后所有安装、运行操作都基于激活后的 python。这样至少终端这一侧的解释器是确定的。4. 虚拟环境与工作目录让运行结果可复现的两道护栏前两章解决能不能运行这一章解决运行结果对不对。代码第一次能跑、换台机器或换个目录就报错九成是环境隔离和路径解析出了问题。这两件事在 VSCODE 里都属于看不见摸不着但随时坑你的设置值得单独讲。4.1 用 venv 隔离环境创建、激活与解释器切换为什么需要虚拟环境。第三方包装在全局 site-packages 里项目一多就会打架A 项目用 numpy 1.xB 项目用 numpy 2.x全局只有一个版本必然有一个项目跑不了。虚拟环境给每个项目一份独立的包目录pip 装的包互不干扰是 Python 项目管理的基本功。创建虚拟环境在 VSCODE 集成终端里执行python -m venv .venv命令含义用当前 python 指向的解释器在当前目录生成一个名为 .venv 的虚拟环境目录。目录里有一套独立的 python.exe 和 pip。注意创建不等于激活激活是下一步。WindowsPowerShell激活.\.venv\Scripts\Activate.ps1Linux / macOS 激活source .venv/bin/activate激活成功的标志是终端提示符前出现 (.venv)之后敲 python 和 pip 都走虚拟环境。如果你的 PowerShell 激活时提示禁止运行脚本之类的错误那是因为执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令的作用允许当前用户运行本地签名和远程下载后签名的脚本。执行策略只改当前用户范围即可别动全局配置。VSCODE 的解释器切换仍然不能省。终端激活只影响终端命令运行按钮和调试器不读终端状态只看状态栏解释器。所以激活完还要执行命令面板里的 Python: Select Interpreter选 .venv 那一条。如果列表里没出现检查设置python.venvPath是否指向了虚拟环境所在目录或者直接手动浏览到 .venv/Scripts/python.exe。注意创建 venv 时可以加--system-site-packages让虚拟环境借用全局包但我不建议开。开了等于没隔离以后排查包冲突时你会花双倍时间。4.2 相对路径翻车的根因当前工作目录与文件目录不是一回事这是带人入门时讲得最多的一个点也是运行 Python 文件时最隐蔽的差异。看这段代码import pandas as pd df pd.read_csv(data/raw/train.csv) print(df.shape)用运行按钮跑报 FileNotFoundError在文件所在目录打开终端手动跑正常输出。为什么因为运行按钮所在的终端工作目录是工作区根目录——你打开 VSCODE 时选中的那个文件夹。相对路径 data/raw/train.csv 是相对于这个工作目录解析的不是相对于代码文件。代码在 src/main.py数据在 src/data/raw/train.csv但从项目根目录去解析 src/data 当然找不到。三种解决办法按优先级代码里用 pathlib 锚定文件位置不依赖任何运行方式from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent df pd.read_csv(BASE_DIR / data/raw/train.csv)Path(__file__)是当前文件路径.resolve()把可能的符号链接和相对路径解析成绝对路径.parent逐级向上取目录。这份代码不管用运行按钮、F5、终端还是打包成 exe行为都一致是我最推荐的方式。调 launch.json 的 cwdcwd: ${fileDirname}这条把调试和运行的工作目录固定在当前文件所在目录适合目录结构简单的脚本。缺点是一旦你从 main.py 切到另一个目录下的工具脚本工作目录跟着变行为依赖当前打开了哪个文件。终端手动运行前先 cd 到相关目录适合交互式探索不适合需要反复运行的正式脚本。我的习惯是数据项目一律 pathlib 写法一次性脚本用 cwd终端方式只用于临时验证。你不需要三种都记住但必须理解相对路径的基准是工作目录不是文件目录这句话。5. VSCODE 运行 Python 的常见问题排查5 条高频踩坑记录前四章把链路讲完了这一章直接给排查手册。下面五条都是被反复问过的高频问题按现象、原因、解决三段写照着对就能少走弯路。5.1 运行按钮是灰色的或提示无法找到 Python 解释器现象打开 .py 文件右上角没有运行按钮或者按钮存在但点了提示无法找到 Python 解释器。原因三选一——没装 Microsoft 的 Python 插件装了插件但 VSCODE 没发现任何解释器发现了但你没选。最后一种最常见尤其你用的是 conda 或者手动安装到非默认目录的 Python。解决先确认插件已启用再执行 Python: Select Interpreter如果列表为空或没有目标环境点浏览手动定位 python.exe。Windows 常见位置是 C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\python.exe。如果这一步连候选都没有回到第 2 章的版本验证先确认解释器真的存在。5.2 终端报python 不是内部或外部命令现象终端执行 python hello.py系统直接说命令不存在Linux 上则是 python: command not found。原因Windows 安装时没勾 Add python.exe to PATHLinux 发行版只装 python3 不装 python 这个别名。解决Windows 的情况重装 Python 并勾上 PATH 是代价最小的方案别手动改系统环境变量容易把用户变量和系统变量的顺序搞乱。Linux 改用 python3或者which python3确认解释器在不在。如果你是刚用 apt 装完大概率还要补sudo apt install python3-pip否则后面 pip 也找不到。5.3 import 报 No module named numpy但 pip list 里明明有 numpy现象代码 import numpy 报 ModuleNotFoundError你跑到终端敲 pip listnumpy 赫然在列。原因运行按钮用的是 VSCODE 选中的解释器pip list 看的是终端当前默认解释器。两者不是同一个环境。典型场景系统 Python 3.9 里装了 numpy但 VSCODE 状态栏选的是 Anaconda 的 Python 3.11或者刚建了 .venv 但 VSCODE 还指着全局环境。解决别用 pip list 猜让代码自己报身份import sys print(sys.executable)这段代码的作用打印当前解释器的绝对路径。在 VSCODE 里跑一次拿到路径 A再在终端执行python -c import sys; print(sys.executable)拿到路径 B。A 和 B 不一致问题就定位了。让 VSCODE 选中 B 那个环境然后用python -m pip install numpy装包。记住一条python -m pip永远比裸敲 pip 可靠它绑定的是具体解释器的包管理器。Python 安装第三方库最不容易踩坑的方式就是这种解释器命令 -m pip的组合。5.4 open(data.txt) 报 FileNotFoundError现象open 一个和 .py 文件同目录的文件用运行按钮跑就是找不到很玄学明明文件就在旁边。原因第 4 章讲过的老问题——工作目录是工作区根目录不是文件目录。程序在根目录找 data.txt当然看不到 src/data.txt。解决三选一。launch.json 加cwd: ${fileDirname}代码改用Path(__file__).parent / data.txt终端先 cd 再跑。三个解法选一个固定下来别今天用这个明天用那个否则你会被自己的不一致行为坑第二次。5.5 代码改了运行按钮执行的还是旧版本现象把 print(a) 改成 print(b)点运行输出还是 a。原因文件没有保存。运行按钮执行的是磁盘上的内容不是编辑器缓冲区里的内容。改完忘 CtrlS 是 Python 入门阶段最常见、也最好笑的翻车现场。解决两个办法。改完习惯性 CtrlS或者在设置里搜 files.autoSave 设为 afterDelay让编辑器在停止输入后自动保存。如果用了 Code Runner把 code-runner.saveFileBeforeRun 打开运行前自动保存这个开关对经常忘保存的人非常实用。6. 把运行这一步打磨顺Code Runner 的 3 个配置项与一键验证最后一章不讲新概念给两个立刻能用的技巧Code Runner 最关键的三个配置和一个 5 秒环境自检脚本。6.1 Code Runner 的三个高频配置项在 settings.json 里追加{ code-runner.runInTerminal: true, code-runner.saveFileBeforeRun: true, code-runner.clearPreviousOutput: true }参数说明runInTerminal让输出走集成终端否则 Code Runner 默认走输出面板那个面板不支持 input() 交互输入saveFileBeforeRun对应第 5 章末尾的旧代码问题运行前自动保存clearPreviousOutput每次运行前清空旧输出避免新旧结果混在一起看花眼。6.2 一个 5 秒的环境自检脚本我每进入一个新项目写的第一段代码永远是这段import os import sys print(解释器:, sys.executable) print(工作目录:, os.getcwd()) print(文件目录:, os.path.dirname(__file__))这段脚本的作用一次打印出解释器路径、当前工作目录、代码文件目录。三行输出对照一下环境对不对、路径基准在哪一目了然。这就是我现在的固定流程建好 .venv、在 VSCODE 里选中它、跑一遍自检脚本确认三行输出符合预期然后才开始写业务代码。别看这几步简单环境问题一旦发生排查时间永远比这几秒钟贵得多。希望帮到你。本文还有配套的精品资源点击获取 VSCODE中运行Python文件全指南：解释器、虚拟环境与常见报错排查
简介面向Python初学者的VSCode运行配置指南以Word文档形式呈现系统梳理在Visual Studio Code中从零开始运行Python文件的关键流程。内容围绕环境搭建与基础操作展开涵盖Python与VSCode安装、官方Python扩展安装、创建脚本文件、选择解释器以及右键菜单运行、播放按钮运行、终端指定路径等多种启动方式步骤清晰且配有说明适合刚接触Python或希望规范开发环境的新手参照使用。文档附带简单示例输出可帮助读者直观理解运行原理减少环境配置中的常见困惑。资源包共1个docx文件大小约303KB体积小巧便于离线阅读或打印学习。该资源已有534人学习内容实用聚焦能在短时间内帮助读者掌握VSCode中Python文件的基本运行流程为后续编程练习打下基础。1. 在 VSCODE 中运行 Python 文件先搞清楚你卡在哪一步先把场景摆出来你在 VSCODE 里写好了第一段 Python 代码点右上角的三角按钮等了半天编辑器下方弹出一行红字无法找到 Python 解释器。换成在终端里敲 python hello.py又被告知 python 不是内部或外部命令。这两句话是 Python 入门路上最常见的拦路虎也恰恰说明在 VSCODE 中运行 Python 文件并不是装个 VSCODE 就能跑的事——它涉及解释器路径、插件、工作区信任、运行配置、虚拟环境和路径解析六件事。下面按顺序拆开讲新手能从头跟到尾被各种奇怪报错折腾过的入门用户也能直接跳到第 5 章对照排查。2. 运行 Python 文件前的环境准备解释器、插件与工作区三大件很多人搜完 vscode 安装教程把编辑器装好打开 .py 文件就开始期待那个绿色三角按钮出现。结果按钮不出现或者出现了点了没反应。这不是 VSCODE 的问题而是运行 Python这个动作依赖三样东西同时就位本机装好的 Python 解释器、VSCODE 里的 Python 插件、以及一个被信任的工作区。2.1 先把 Python 装对安装包选择、PATH 勾选与版本验证Windows 是重灾区。从 Python 官网下载安装包装完一路 Next 很容易漏掉最关键的一步安装窗口里有一个 Add python.exe to PATH 的勾选框。这个勾决定你能不能直接在终端里敲 python 命令。没勾的话VSCODE 集成终端里运行文件时会直接报python 不是内部或外部命令。如果已经装完且没勾 PATH有两个补救办法。一是重新运行安装包选 Modify勾上这个选项再走一遍二是手动把 Python 安装目录和它的 Scripts 子目录加进系统环境变量。我一般推荐前者重装一次不到两分钟不容易把系统 PATH 改乱而且重装不会动你已装的第三方包。装完以后先在终端里验证解释器本身是好的python --version pip --version验证命令说明第一条打印当前默认 Python 的版本号第二条确认包管理器 pip 能被找到。两个都有输出说明解释器本体没毛病后面出问题就该往 VSCODE 侧找。如果 python 没反应但你的 Python 确实装了试试py --version——Windows 的 py 启动器经常被单独安装py -3 --version可以明确指定 Python 3。Linux 和 macOS 的情况不同Linux 发行版很多预装 Python 3 但命令叫 python3macOS 系统自带的老版本 Python 最好别碰。另装一份官方 Python或者用apt install python3 python3-pip、dnf install python3 python3-pip安装都行。如果你在 VSCODE 里通过 WSL 做开发判断标准不变只是终端变成了 WSL 里的 bash命令名按 Linux 那套来。最终判断标准只有一个你能用某条命令稳定打印出版本号就把它当成项目默认解释器。2.2 VSCODE 端三件套Python 插件、Code Runner 与工作区信任Python 插件是必须项。扩展市场搜 Python认准发布者是 Microsoft 的那个。它提供三样东西解释器选择、运行按钮和调试支持。没有它.py 文件在 VSCODE 里就是纯文本右上角不会有运行按钮F5 也不能启动调试。vscode 配置 python 环境的第一步几乎都是先装这个插件。Code Runner 是可选项。它提供右键Run Code和另一套运行按钮胜在灵活第 6 章会讲它的关键参数。但它和 Python 插件的运行行为不完全一致新手阶段建议只保留一个主运行方式避免混用后搞不清楚到底是谁在跑你的代码。工作区信任是个容易被忽略的开关。VSCODE 较新版本加入了工作区信任机制打开一个不在信任列表里的文件夹编辑器顶部会弹条幅问你是否信任此文件夹的作者。点不信任的话调试、任务运行、部分插件功能会被禁用表现就是一切运行入口全部失效。自己写的项目直接点信任即可这个机制主要防的是网上下载的未知代码一打开就自动执行不建议全局关闭。装完插件、信任了工作区还差最后一步选择解释器。按CtrlShiftP打开命令面板输入 Python: Select Interpreter从列表里选一个。列表里通常有系统 Python、Anaconda、虚拟环境等多个候选。选完以后底部状态栏右侧会显示当前解释器的路径和版本。提示状态栏右侧显示的解释器才是运行按钮和调试器真正使用的解释器你在终端里敲 python 用的可能完全是另一个。排查环境类报错时永远先确认这两处是不是同一个。3. 在 VSCODE 中运行 Python 文件的三种方式按钮、调试与终端环境就位之后运行本身有三条路右上角运行按钮、F5 调试、终端手动执行。它们执行同一份代码但工作目录、解释器来源、可用的调试能力都不一样。很多人在家能跑、换台机器就跑不起来本质是没搞清自己用的是哪条路。3.1 右上角运行按钮它到底帮你执行了什么点运行按钮VSCODE 的实际动作是在集成终端里调用当前选中的解释器执行当前打开的文件。以 Windows PowerShell 为例生成的命令长这样 C:/Users/你的用户名/AppData/Local/Programs/Python/Python39/python.exe c:/Users/你的用户名/Desktop/demo/hello.py这条命令的含义是 PowerShell 的调用运算符后面跟着解释器完整路径再后面是被运行文件的完整路径。注意中间没有任何 cd 操作——也就是说终端的工作目录是 VSCODE 打开项目时的工作区根目录而不是文件所在目录。这是第 4 章相对路径翻车的起点先记住这个事实。Python 插件有个设置项python.terminal.executeInFileDir默认 false。设为 true 后点运行按钮会自动把终端工作目录切到当前文件所在目录能解决一部分路径问题但它改变的是终端行为不是调试器行为——F5 调试依然按 launch.json 来所以别指望一个开关通吃。3.2 F5 调试运行launch.json 的最小配置与参数调试适合排查逻辑错误断点、变量监视、单步执行。第一次按 F5VSCODE 会引导你创建 launch.json。一个能跑通当前文件的最小配置如下{ version: 0.2.0, configurations: [ { name: Python 调试当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal } ] }参数逐项说明name 是调试配置的名字显示在调试面板的下拉列表里可以随便起type 写debugpy这是当前 Python 插件使用的调试器类型旧教程里写python新装环境一律用 debugpyrequest 固定写launch表示启动新进程来调试另一个取值attach用于附着到已在运行的进程日常开发用不到program 是要运行的程序${file}是 VSCODE 变量代表当前激活的文件如果想固定调试项目入口可以改成${workspaceFolder}/main.pyconsole 决定程序的标准输入输出去哪里integratedTerminal输出到集成终端保留完整交互internalConsole输出到调试控制台界面干净但不支持 input() 交互输入。实际项目中几乎总会用到另外两个参数args: [--epochs, 50], cwd: ${fileDirname}参数说明args是传给程序的命令行参数不写的话你在终端里跑python train.py --epochs 50和 F5 调试的行为就不同cwd是程序的工作目录。很多训练脚本用相对路径读数据如果你在终端跑的时候习惯 cd 到数据目录那调试时就必须把 cwd 指到同一个目录否则同样的代码两种运行方式结果不同排查起来非常迷惑。3.3 终端手动运行python、python3、py 三个命令的区别终端运行是最朴素也最可控的方式但命令怎么敲取决于操作系统命令常见可用的系统说明pythonWindows、部分 macOS指向 PATH 中第一个 Python受虚拟环境影响python3Linux、macOSLinux 发行版默认命令Windows 上通常不存在pyWindowspy 启动器py -3 main.py明确用 Python 3判断方法很简单三条命令挨个在终端敲一遍哪条能打印出版本号就用哪条。但这里有个老坑同一个终端里 python 指向谁取决于你有没有先激活虚拟环境。激活后python 是虚拟环境里的没激活python 是系统的。你要是先敲了pip install numpy再激活虚拟环境跑代码报 No module named 就一点也不冤。我个人的习惯Windows 上用 py 启动器进入项目后第一时间激活虚拟环境然后所有安装、运行操作都基于激活后的 python。这样至少终端这一侧的解释器是确定的。4. 虚拟环境与工作目录让运行结果可复现的两道护栏前两章解决能不能运行这一章解决运行结果对不对。代码第一次能跑、换台机器或换个目录就报错九成是环境隔离和路径解析出了问题。这两件事在 VSCODE 里都属于看不见摸不着但随时坑你的设置值得单独讲。4.1 用 venv 隔离环境创建、激活与解释器切换为什么需要虚拟环境。第三方包装在全局 site-packages 里项目一多就会打架A 项目用 numpy 1.xB 项目用 numpy 2.x全局只有一个版本必然有一个项目跑不了。虚拟环境给每个项目一份独立的包目录pip 装的包互不干扰是 Python 项目管理的基本功。创建虚拟环境在 VSCODE 集成终端里执行python -m venv .venv命令含义用当前 python 指向的解释器在当前目录生成一个名为 .venv 的虚拟环境目录。目录里有一套独立的 python.exe 和 pip。注意创建不等于激活激活是下一步。WindowsPowerShell激活.\.venv\Scripts\Activate.ps1Linux / macOS 激活source .venv/bin/activate激活成功的标志是终端提示符前出现 (.venv)之后敲 python 和 pip 都走虚拟环境。如果你的 PowerShell 激活时提示禁止运行脚本之类的错误那是因为执行策略限制Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令的作用允许当前用户运行本地签名和远程下载后签名的脚本。执行策略只改当前用户范围即可别动全局配置。VSCODE 的解释器切换仍然不能省。终端激活只影响终端命令运行按钮和调试器不读终端状态只看状态栏解释器。所以激活完还要执行命令面板里的 Python: Select Interpreter选 .venv 那一条。如果列表里没出现检查设置python.venvPath是否指向了虚拟环境所在目录或者直接手动浏览到 .venv/Scripts/python.exe。注意创建 venv 时可以加--system-site-packages让虚拟环境借用全局包但我不建议开。开了等于没隔离以后排查包冲突时你会花双倍时间。4.2 相对路径翻车的根因当前工作目录与文件目录不是一回事这是带人入门时讲得最多的一个点也是运行 Python 文件时最隐蔽的差异。看这段代码import pandas as pd df pd.read_csv(data/raw/train.csv) print(df.shape)用运行按钮跑报 FileNotFoundError在文件所在目录打开终端手动跑正常输出。为什么因为运行按钮所在的终端工作目录是工作区根目录——你打开 VSCODE 时选中的那个文件夹。相对路径 data/raw/train.csv 是相对于这个工作目录解析的不是相对于代码文件。代码在 src/main.py数据在 src/data/raw/train.csv但从项目根目录去解析 src/data 当然找不到。三种解决办法按优先级代码里用 pathlib 锚定文件位置不依赖任何运行方式from pathlib import Path BASE_DIR Path(__file__).resolve().parent.parent df pd.read_csv(BASE_DIR / data/raw/train.csv)Path(__file__)是当前文件路径.resolve()把可能的符号链接和相对路径解析成绝对路径.parent逐级向上取目录。这份代码不管用运行按钮、F5、终端还是打包成 exe行为都一致是我最推荐的方式。调 launch.json 的 cwdcwd: ${fileDirname}这条把调试和运行的工作目录固定在当前文件所在目录适合目录结构简单的脚本。缺点是一旦你从 main.py 切到另一个目录下的工具脚本工作目录跟着变行为依赖当前打开了哪个文件。终端手动运行前先 cd 到相关目录适合交互式探索不适合需要反复运行的正式脚本。我的习惯是数据项目一律 pathlib 写法一次性脚本用 cwd终端方式只用于临时验证。你不需要三种都记住但必须理解相对路径的基准是工作目录不是文件目录这句话。5. VSCODE 运行 Python 的常见问题排查5 条高频踩坑记录前四章把链路讲完了这一章直接给排查手册。下面五条都是被反复问过的高频问题按现象、原因、解决三段写照着对就能少走弯路。5.1 运行按钮是灰色的或提示无法找到 Python 解释器现象打开 .py 文件右上角没有运行按钮或者按钮存在但点了提示无法找到 Python 解释器。原因三选一——没装 Microsoft 的 Python 插件装了插件但 VSCODE 没发现任何解释器发现了但你没选。最后一种最常见尤其你用的是 conda 或者手动安装到非默认目录的 Python。解决先确认插件已启用再执行 Python: Select Interpreter如果列表为空或没有目标环境点浏览手动定位 python.exe。Windows 常见位置是 C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\python.exe。如果这一步连候选都没有回到第 2 章的版本验证先确认解释器真的存在。5.2 终端报python 不是内部或外部命令现象终端执行 python hello.py系统直接说命令不存在Linux 上则是 python: command not found。原因Windows 安装时没勾 Add python.exe to PATHLinux 发行版只装 python3 不装 python 这个别名。解决Windows 的情况重装 Python 并勾上 PATH 是代价最小的方案别手动改系统环境变量容易把用户变量和系统变量的顺序搞乱。Linux 改用 python3或者which python3确认解释器在不在。如果你是刚用 apt 装完大概率还要补sudo apt install python3-pip否则后面 pip 也找不到。5.3 import 报 No module named numpy但 pip list 里明明有 numpy现象代码 import numpy 报 ModuleNotFoundError你跑到终端敲 pip listnumpy 赫然在列。原因运行按钮用的是 VSCODE 选中的解释器pip list 看的是终端当前默认解释器。两者不是同一个环境。典型场景系统 Python 3.9 里装了 numpy但 VSCODE 状态栏选的是 Anaconda 的 Python 3.11或者刚建了 .venv 但 VSCODE 还指着全局环境。解决别用 pip list 猜让代码自己报身份import sys print(sys.executable)这段代码的作用打印当前解释器的绝对路径。在 VSCODE 里跑一次拿到路径 A再在终端执行python -c import sys; print(sys.executable)拿到路径 B。A 和 B 不一致问题就定位了。让 VSCODE 选中 B 那个环境然后用python -m pip install numpy装包。记住一条python -m pip永远比裸敲 pip 可靠它绑定的是具体解释器的包管理器。Python 安装第三方库最不容易踩坑的方式就是这种解释器命令 -m pip的组合。5.4 open(data.txt) 报 FileNotFoundError现象open 一个和 .py 文件同目录的文件用运行按钮跑就是找不到很玄学明明文件就在旁边。原因第 4 章讲过的老问题——工作目录是工作区根目录不是文件目录。程序在根目录找 data.txt当然看不到 src/data.txt。解决三选一。launch.json 加cwd: ${fileDirname}代码改用Path(__file__).parent / data.txt终端先 cd 再跑。三个解法选一个固定下来别今天用这个明天用那个否则你会被自己的不一致行为坑第二次。5.5 代码改了运行按钮执行的还是旧版本现象把 print(a) 改成 print(b)点运行输出还是 a。原因文件没有保存。运行按钮执行的是磁盘上的内容不是编辑器缓冲区里的内容。改完忘 CtrlS 是 Python 入门阶段最常见、也最好笑的翻车现场。解决两个办法。改完习惯性 CtrlS或者在设置里搜 files.autoSave 设为 afterDelay让编辑器在停止输入后自动保存。如果用了 Code Runner把 code-runner.saveFileBeforeRun 打开运行前自动保存这个开关对经常忘保存的人非常实用。6. 把运行这一步打磨顺Code Runner 的 3 个配置项与一键验证最后一章不讲新概念给两个立刻能用的技巧Code Runner 最关键的三个配置和一个 5 秒环境自检脚本。6.1 Code Runner 的三个高频配置项在 settings.json 里追加{ code-runner.runInTerminal: true, code-runner.saveFileBeforeRun: true, code-runner.clearPreviousOutput: true }参数说明runInTerminal让输出走集成终端否则 Code Runner 默认走输出面板那个面板不支持 input() 交互输入saveFileBeforeRun对应第 5 章末尾的旧代码问题运行前自动保存clearPreviousOutput每次运行前清空旧输出避免新旧结果混在一起看花眼。6.2 一个 5 秒的环境自检脚本我每进入一个新项目写的第一段代码永远是这段import os import sys print(解释器:, sys.executable) print(工作目录:, os.getcwd()) print(文件目录:, os.path.dirname(__file__))这段脚本的作用一次打印出解释器路径、当前工作目录、代码文件目录。三行输出对照一下环境对不对、路径基准在哪一目了然。这就是我现在的固定流程建好 .venv、在 VSCODE 里选中它、跑一遍自检脚本确认三行输出符合预期然后才开始写业务代码。别看这几步简单环境问题一旦发生排查时间永远比这几秒钟贵得多。希望帮到你。本文还有配套的精品资源点击获取