VS Code提示“Python was not found”或无法选择解释器怎么办

在 VS Code 中编写或运行 Python 脚本时，如果集成终端提示 Python was not found; run without arguments to install from the Microsoft Store...，或者状态栏提示 Select Interpreter、点击后找不到任何可用的 Python 解释器，其核心根源只有三处：系统尚未安装标准 Python 或安装时未将路径写入系统环境变量 PATH、Windows 系统的“应用执行别名”劫持了 python 命令，或者 VS Code 的 Python 扩展未能自动扫描到解释器安装路径。本文按照自浅入深的排查次序，提供定位与修复方案。

一、问题定位与排查流程

面对报错时，首要任务是明确“故障发生在系统全局层还是编辑器层”。在开始修改设置前，按下快捷键 Ctrl + ` 打开 VS Code 集成终端，也可以直接在系统开始菜单中打开普通的“命令提示符”（CMD），执行以下版本检测命令：

python --version

根据终端返回的结果，可以迅速锁定问题类型并选择对应的处置方案：

• 情况 A（系统未配置或被应用商店劫持）：提示“Python was not found”并建议访问应用商店，或者直接弹出了 Windows Store 窗口。这是 Windows 系统的应用别名机制引起的冲突。
• 情况 B（未加入环境变量）：提示“'python' 不是内部或外部命令，也不是可运行的程序”。说明 Python 尚未安装，或者安装时遗漏了添加 PATH 的选项。
• 情况 C（系统正常但编辑器无法识别）：终端能正常打印出 Python 3.x.x 版本号，但 VS Code 右下角依然显示未选择解释器，且解释器列表中没有任何选项。这属于 VS Code 扩展扫描范围问题。

二、关闭 Windows“应用执行别名”（解决 Microsoft Store 劫持）

Windows 10 和 Windows 11 在系统默认配置中加入了一项名为“应用执行别名”（App Execution Aliases）的机制。当系统中尚未通过应用商店安装 Python 时，系统目录下预置了名为 python.exe 和 python3.exe 的空占位符文件。当在终端键入 python 时，系统优先匹配到该别名，并自动重定向到应用商店下载页或抛出“Python was not found”警告。

如果已经从 Python 官网（python.org）安装了官方发行版，但终端依然抛出此错误，说明别名的优先级覆盖了实际安装路径。关闭该别名的具体操作如下：

1. 按下快捷键 Win + I 打开 Windows“设置”。
2. 依次进入：应用 > 高级应用设置 > 应用执行别名（Windows 10 中为：应用 > 应用和功能 > 管理应用执行别名）。
3. 在列表中找到名为 应用安装程序 (python.exe) 和 应用安装程序 (python3.exe) 的开关。
4. 将这两个选项全部切换为“关闭”状态。

关闭后，系统将跳过占位符，直接按照 PATH 环境变量中的定义去寻找实际的解释器执行程序。

三、检查并修复 PATH 环境变量

如果关闭应用别名后，在终端运行 python 提示“不是内部或外部命令”，说明操作系统并不知道 python.exe 存放在硬盘的哪个文件夹下。这通常是因为在安装 Python 时，忘记勾选安装程序首页的“Add python.exe to PATH”。

方法 1：运行安装包直接修复（推荐）

最稳妥且不易出错的途径是重新打开此前下载的 Python 官方安装包（例如 python-3.11.x-amd64.exe）：

• 在弹出的界面中点击 Modify（修改）。
• 在 Optional Features（可选功能）界面保持默认，点击 Next。
• 在 Advanced Options（高级选项）页面中，务必勾选 Add Python to environment variables（将 Python 添加到环境变量）。
• 点击 Install 完成安装并点击关闭。

方法 2：手动添加系统环境变量

如果安装包已删除，可手动把 Python 路径写入系统变量：

1. 找到你的 Python 实际安装路径。常见默认路径为：
   C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python311\
   或者自定义路径如：C:\Python311\。
2. 按下 Win + R 键，输入 sysdm.cpl 并回车，打开“系统属性”。
3. 切换到高级标签页，点击底部的环境变量。
4. 在“用户变量”或“系统变量”中找到名为 Path 的项，选中后点击编辑。
5. 点击新建，将以下两行路径分别添加进去（请将路径替换为你本地的实际绝对路径）：

   C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python311\
   C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python311\Scripts\

6. 逐层点击“确定”保存退出。

四、在 VS Code 中正确选择与指定解释器

当系统环境已经能够正常识别 python --version 后，VS Code 应当能够自动列出系统中的解释器。但若编辑器仍然显示无解释器，或者你使用的是自定义目录、Conda 或虚拟环境，可以通过手动指定路径解决。

1. 确认 Python 扩展状态

VS Code 本身是一个通用编辑器，其对 Python 的识别、调试和解释器切换能力来自于由 Microsoft 发布的官方扩展 Python（扩展 ID：ms-python.python）。在 VS Code 左侧边栏点击扩展图标（快捷键 Ctrl + Shift + X），搜索 Python，确保该扩展处于“已启用”（Enabled）状态。如果扩展被禁用或未安装，VS Code 不会提供选择解释器的指令面板。

2. 使用命令面板手动指定路径

如果官方扩展已启用，但列表仍为空，请按照以下步骤手动关联已有的 Python 可执行程序：

1. 按下快捷键 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）打开命令面板。
2. 输入并选择：Python: Select Interpreter（选择解释器）。
3. 若列表中未自动出现目标版本，点击顶部的 Enter interpreter path...（输入解释器路径）。
4. 点击 Find...（浏览），在文件资源管理器中直接定位到 python.exe 文件所在的位置并选中确认。

五、虚拟环境与多环境配置

在实际开发中，项目往往不会使用系统全局的 Python，而是使用独立的虚拟环境（如 venv 或 conda）。如果虚拟环境未能被 VS Code 感知，可采取以下标准操作：

1. 标准 venv 环境的快速识别

推荐直接在当前项目根目录下创建标准命名的虚拟环境。进入项目目录后，在终端执行：

python -m venv .venv

当环境创建完毕后，VS Code 的 Python 扩展通常会立刻弹出一个提示框：We noticed a new environment has been created. Do you want to select it for the workspace folder?（检测到新环境，是否为工作区选择？），直接点击 Yes 即可。如果未弹出提示，按下 Ctrl + Shift + P 输入 Python: Select Interpreter，列表顶部会自动将 ./.venv/Scripts/python.exe 识别为 Recommended（推荐）。

2. 通过工作区 settings.json 显式固化

为了防止团队协作或多次打开项目时重复选择解释器，可以在当前项目的根目录下创建 .vscode/settings.json 文件，并显式指定解释器相对路径：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"
}

对于 macOS 或 Linux 系统，由于可执行文件位于 bin 目录且没有 .exe 后缀，配置应写为：

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

六、排查总结与对照清单

下表归纳了常见的故障表现、根本诱因与快速验收方法，供排查时对照参考：