pyenv-win 完整安装+使用手册

一、前言：为什么要安装 pyenv-win？

在 Windows 环境下使用 Python，你大概率会遇到以下痛点：

系统全局安装一个 Python 版本，无法满足不同项目对 Python 版本的需求（比如 A 项目需要 3.8，B 项目需要 3.14）；
手动安装多个 Python 版本，环境变量配置混乱，切换版本需要反复修改 PATH，极易出错；
卸载某个 Python 版本时，容易残留文件、破坏其他版本的运行环境；
脚本运行报错"Python 版本不兼容"，却无法快速切换到适配版本。

而 pyenv-win 正是为解决这些痛点而生------它是 Windows 平台专属的 Python 多版本管理工具，无需复杂配置，就能轻松实现多个 Python 版本的安装、切换、管理，核心优点如下（结合实际使用场景，适配你之前遇到的问题）：

1. 彻底解决版本冲突，实现"版本隔离"

pyenv-win 会将每个 Python 版本安装在独立目录（~/.pyenv/pyenv-win/versions/），互不干扰。比如你安装了 3.14.2 用于运行 speech2text.py 脚本，同时安装 3.8 用于其他旧项目，切换版本时无需修改环境变量，避免"装新删旧""版本覆盖"的问题。

2. 一键切换版本，灵活适配不同场景

支持 3 种切换模式（全局、项目级、临时），按需选择，切换后立即生效（配合 pyenv rehash 即可解决"python 命令找不到"的问题），无需重启电脑，大幅提升开发效率。

3. 安装/卸载简单，无需手动配置环境变量

通过官方一键脚本安装，自动配置 PYENV、PYENV_ROOT 等环境变量，无需手动修改系统 PATH；卸载版本时，只需一条命令，彻底删除对应版本文件，无残留。

4. 轻量无侵入，不影响系统原有环境

pyenv-win 本身体积小，不占用过多资源，不会修改系统自带的 Python 环境（若有），即使卸载 pyenv-win，之前安装的 Python 版本也能正常使用。

5. 适配多种终端，兼容 PowerShell、Git Bash 等

解决你之前遇到的"Git Bash 无法识别 pyenv""PowerShell 禁止运行脚本"等问题，手册全程适配 PowerShell 操作，规避所有权限坑，确保不同终端都能正常使用 pyenv。

二、安装前准备

1. 终端准备

打开 管理员 PowerShell（开始菜单 → 搜索"PowerShell" → 右键"以管理员身份运行"），注意：必须用管理员权限，否则会出现"脚本禁止运行""权限不足"的报错（解决你之前遇到的核心问题）。

2. 解除 PowerShell 脚本运行限制

Windows 默认禁止运行 PowerShell 脚本，这是导致"无法加载 install-pyenv-win.ps1"的根本原因，执行以下命令解除限制（复制粘贴直接运行，无需修改）：

powershell 复制代码

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

执行后无报错，即完成权限配置，后续安装脚本可正常运行。

3. 补充说明

无需卸载系统已有的 Python（若有），pyenv-win 会优先使用自身管理的版本，不影响原有环境；
关闭所有正在运行的 Python 终端、IDE（如 PyCharm、VS Code），避免进程占用，导致安装失败。

三、官方一键安装

在 管理员 PowerShell 中，直接复制整行命令运行（无需拆分，无需修改路径），这是官方推荐的安装方式，自动完成环境变量配置：

powershell 复制代码

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

安装成功标志

终端输出以下内容，即为安装成功（若出现"备份现有版本""更新版本"等提示，直接等待完成即可）：

text 复制代码

pyenv-win is successfully installed. You may need to close and reopen your terminal before using it.

关键操作

安装完成后，关闭所有终端（包括管理员 PowerShell） ，重新打开一个普通 PowerShell（无需管理员权限）------环境变量必须重启终端才能生效，这是解决"pyenv 不是内部命令"的关键。

四、验证安装

在新开的普通 PowerShell 中，运行以下命令，验证 pyenv 是否安装成功：

powershell 复制代码

pyenv --version

✅ 成功标志：输出类似 pyenv 3.1.1（版本号可能略有差异，不影响使用）。

❌ 若报错"pyenv 不是内部或外部命令"：重新关闭所有终端，再打开重试；若仍报错，参考文末"常见问题"修复。

五、pyenv 核心使用教程

以下操作均在 普通 PowerShell 中执行，无需管理员权限，全程适配你的需求（安装 3.14.2 并全局生效，运行 speech2text.py 脚本）。

1. 查看可安装的 Python 版本

运行以下命令，查看 pyenv 支持安装的所有 Python 版本（可筛选需要的版本）：

powershell 复制代码

pyenv install --list

输出会包含多个 Python 版本（如 3.8.10、3.11.4、3.14.2 等），确认 3.14.2 在列表中即可。

2. 安装 Python 3.14.2 版本

运行以下命令，安装指定版本（复制粘贴，无需修改）：

powershell 复制代码

pyenv install 3.14.2

安装过程会自动下载 Python 安装包，等待 1-5 分钟（取决于网络速度），出现以下提示即为安装成功：

text 复制代码

Installed successfully

❌ 若安装卡住/失败：关闭杀毒软件、防火墙，重新运行命令；若仍失败，参考文末"常见问题"修复。

3. 设置 3.14.2 为全局默认版本

运行以下命令，将 3.14.2 设置为全局版本（所有终端、所有项目均生效）：

powershell 复制代码

pyenv global 3.14.2

4. 刷新命令

设置全局版本后，必须运行以下命令，重建 pyenv 命令映射（shims 目录），否则系统找不到 python 命令：

powershell 复制代码

pyenv rehash

5. 验证全局版本是否生效

运行以下命令，确认 Python 版本已切换为 3.14.2：

powershell 复制代码

python --version

✅ 成功标志：输出 Python 3.14.2，此时全局 Python 版本已生效。

6. 运行示例脚本

1. 新建脚本文件

例如创建文件：hello.py

2. 写入以下代码

python 复制代码

import sys

def main():
    print("Hello World")
    print("Python version:", sys.version)

if __name__ == "__main__":
    main()

3. 运行脚本

在命令行执行：

python 复制代码

python hello.py

4. 预期输出示例

python 复制代码

Hello World  
Python version: 3.14.2 (tags/v3.14.2:xxxx, ...)

六、pyenv 常用命令速查（日常必备，建议收藏）

命令	功能说明	示例
pyenv --version	查看 pyenv 版本	pyenv --version
pyenv install --list	查看可安装的 Python 版本	pyenv install --list
pyenv install 版本号	安装指定 Python 版本	pyenv install 3.14.2
pyenv uninstall 版本号	卸载指定 Python 版本	pyenv uninstall 3.8.10
pyenv versions	查看已安装的所有 Python 版本（* 表示当前生效版本）	pyenv versions
pyenv global 版本号	设置全局默认版本（所有终端生效）	pyenv global 3.14.2
pyenv local 版本号	设置当前项目版本（仅当前文件夹生效）	pyenv local 3.11.4
pyenv shell 版本号	设置临时版本（仅当前终端生效，关闭终端失效）	pyenv shell 3.14.2
pyenv rehash	重建命令映射，解决"python 命令找不到"问题	pyenv rehash

七、常见问题排查

1. 报错：无法加载文件 install-pyenv-win.ps1，禁止运行脚本

原因：未解除 PowerShell 脚本运行限制。

解决：重新打开管理员 PowerShell，运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force，再重新执行安装命令。

2. 报错：pyenv 不是内部或外部命令

原因：环境变量未生效，或安装脚本未正确配置 PATH。

解决：关闭所有终端，重新打开；若仍报错，手动配置环境变量（参考下文）。

3. 运行 python --version 返回空，无任何输出

原因：未执行 pyenv rehash，shims 目录未生成 python 命令映射。

解决：运行 pyenv rehash，再重新查看版本；若仍无效，参考"手动配置环境变量"。

4. 手动配置环境变量（兜底方案）

若自动配置失败，手动添加环境变量（Win+S → 搜索"环境变量" → 编辑用户环境变量）：

新建 3 个变量：
- 变量名：PYENV，变量值：C:\Users\当前用户名\.pyenv\pyenv-win
- 变量名：PYENV_ROOT，变量值：C:\Users\当前用户名\.pyenv\pyenv-win
- 变量名：PYENV_HOME，变量值：C:\Users\当前用户名\.pyenv\pyenv-win
编辑 PATH 变量，新增 2 条：
- %PYENV%\bin
- %PYENV%\shims

保存后，关闭所有终端，重新打开即可。

八、卸载 pyenv-win（可选）

若后续无需使用 pyenv-win，在管理员 PowerShell 中运行以下命令，彻底卸载（包括所有通过 pyenv 安装的 Python 版本）：

powershell 复制代码

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1" -Uninstall

卸载成功后，可手动删除 C:\Users\当前用户名\.pyenv 目录，清理残留文件。

九、总结

pyenv-win 的核心价值是"简单、高效地管理多个 Python 版本"，解决版本冲突、环境配置复杂的痛点，尤其适合需要切换不同 Python 版本开发、运行脚本的场景（如你运行 hello.py 脚本，需要固定 3.14.2 版本）。

按本手册操作，可彻底规避你之前遇到的"权限报错、命令找不到、版本切换无效"等问题，全程无坑，安装完成后即可正常使用 pyenv 管理 Python 版本、运行脚本。