使用 pyenv-win 在 Windows 上进行 Python 环境管理的终极指南

1. 核心理念：为什么要用 pyenv？

在开发中，你可能会遇到以下场景：

• 项目 A 需要 Python 3.8。
• 项目 B 需要 Python 3.10。
• 你想尝试最新的 Python 3.14，但又不想把现有项目搞乱。

手动在系统中安装多个 Python 版本，并通过修改环境变量来切换，是一场灾难。pyenv 就是为了解决这个问题而生的。

pyenv 的核心作用：

• 让你能够轻松地安装任意多个 Python 版本。
• 让你能够一键切换全局或单个项目的 Python 版本。
• 它通过一个名为 shims 的巧妙机制，自动地为你调用正确的 Python 和 pip 版本，而不需要你手动修改任何环境变量。

2. pyenv 的关键概念

• global: 设置一个全局默认的 Python 版本。当你不在任何一个指定了特定版本的项目里时，pyenv 就会使用这个版本。
• local: 为当前文件夹（即你的项目）设置一个特定的 Python 版本。它会在当前目录下创建一个 .python-version 文件来记录这个设置，优先级高于 global。
• shims (垫片/智能快捷方式): 这是 pyenv 的魔法核心。pyenv 会创建一个 shims 文件夹，里面放满了像 python.exe, pip.exe 这样的“假”程序。当你运行 pip 时，你实际上运行的是 shims 里的那个“假”pip，它会智能地判断你当前需要哪个版本的 Python，然后去调用那个版本真正的 pip.exe。
• pyenv rehash: 这个命令的作用是更新 shims。每当你用 pip 安装了一个会提供新命令的工具时（比如 pipx, poetry, uv, django-admin），你就必须运行一次 pyenv rehash，来为这个新命令在 shims 目录里创建一个对应的“智能快捷方式”。

3. 正确的安装与配置 (一次搞定，永绝后患)

第1步：清理旧环境 (最重要的一步)

在安装 pyenv 之前，必须确保你的系统是“干净”的，没有任何由系统或其他方式安装的 Python 干扰。

1. 卸载所有已安装的 Python:
   • 进入 Windows 的“设置” -> “应用” -> “应用和功能”。
   • 搜索 “Python”，将所有找到的 Python 版本（例如 Python 3.8, Python 3.13 等）全部卸载。
2. 清理环境变量 Path:
   • 打开“编辑系统环境变量”。
   • 点击“环境变量”。
   • 分别检查**“用户变量”和“系统变量”**中的 Path 变量。
   • 删除其中所有指向 Python 安装目录的路径（例如 C:\Python38\Scripts, C:\Program Files\python, C:\Users\YourUser\AppData\...\Python 等）。

第2步：安装 pyenv-win

1. 以管理员身份打开 PowerShell。
2. 运行以下命令来安装：

   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"
   

第3步：配置环境变量

安装脚本会自动帮你配置环境变量，但我们必须手动检查并确保其正确无误。

1. 打开“编辑系统环境变量” -> “环境变量”。
2. 在**“系统变量”**中，确认存在以下变量：
   • PYENV：值为 C:\Users\你的用户名\.pyenv\pyenv-win (或者 C:\.pyenv\pyenv-win)
   • PYENV_HOME：值为 C-:\Users\你的用户名\.pyenv\pyenv-win
   • PYENV_ROOT：值为 C:\Users\你的用户名\.pyenv\pyenv-win
3. 在**“系统变量”的 Path 变量中，点击“编辑”，并确保以下两个路径存在，并且位于列表的最顶端**（使用“上移”按钮）：
   • %PYENV_ROOT%\bin
   • %PYENV_ROOT%\shims

第4步：重启与验证

1. 重启你的电脑，以确保所有环境变量的更改都已生效。
2. 重启后，打开一个新的命令提示符 (cmd) 或 PowerShell。
3. 运行验证命令：

   pyenv --version
   # 应该会输出 pyenv-win 的版本号
   
   where python
   # 输出的第一行必须是 ...\.pyenv\pyenv-win\shims\python.bat
   
   where pip
   # 输出的第一行必须是 ...\.pyenv\pyenv-win\shims\pip.bat
   

   如果验证通过，恭喜你，你的 pyenv 环境已经完美配置好了。

4. 日常使用工作流

场景1：安装一个新的 Python 版本

# 查看所有可以安装的版本
pyenv install --list

# 安装一个你需要的版本，例如 3.10.9
pyenv install 3.10.9

# （可选）安装完成后，运行一次 rehash
pyenv rehash

场景2：设置全局默认的 Python 版本

# 查看你已经安装的所有版本，带 * 的是当前激活的
pyenv versions

# 将 3.10.9 设置为全局默认
pyenv global 3.10.9

# 再次验证
pyenv versions
python --version
# 应该输出 Python 3.10.9

场景3：为特定项目设置独立的 Python 版本

# 进入你的项目文件夹
cd D:\MyProjects\Project-A

# 为这个项目设置使用 Python 3.8.10 (假设你已经安装了它)
pyenv local 3.8.10

# pyenv 会自动创建一个 .python-version 文件
# 现在，只要你在这个文件夹里，python 和 pip 都会自动指向 3.8.10
python --version
# 应该输出 Python 3.8.10

# 离开这个文件夹
cd ..

# 再次查看版本，它会自动切换回你的全局版本
python --version
# 应该输出 Python 3.10.9

场景4：安装带命令的工具 (例如 pipx)

这是我们之前问题的核心。

# 1. 用 pip 安装工具
pip install pipx

# 2. 【黄金法则】立刻运行 rehash 来创建 shim
pyenv rehash

# 3. 现在你就可以直接使用新命令了
pipx --version

场景5：结合 venv 虚拟环境进行项目开发 (最佳实践)

pyenv 管理 Python 版本，venv 管理项目的依赖包，两者结合是完美的开发模式。

# 1. 进入你的项目文件夹，并用 pyenv 设置好 Python 版本
cd D:\MyProjects\Project-B
pyenv local 3.10.9

# 2. 使用当前 pyenv 激活的 python，创建一个名为 .venv 的虚拟环境
python -m venv .venv

# 3. 激活这个虚拟环境
# 在 cmd 中:
.venv\Scripts\activate.bat
# 在 PowerShell 中:
.venv\Scripts\Activate.ps1

# 激活后，你的命令行提示符前面会出现 (.venv)
# 4. 在这个环境中安装项目依赖，它们会被装到 .venv 文件夹里，不会污染全局环境
pip install flask requests numpy

# 5. 开发完成后，退出虚拟环境
deactivate

5. 故障排除

• 问题： 命令 pipx (或 poetry, uv 等) 找不到。

  • 原因： 99% 的可能是你安装完它之后，忘记了运行 pyenv rehash。
  • 解决： 运行 pyenv rehash。

• 问题： python --version 显示的版本不是我想要的。

  • 原因： 检查 pyenv versions 看当前激活的是哪个。检查当前目录下是否有 .python-version 文件（pyenv local 的结果）。
  • 解决： 使用 pyenv global 或 pyenv local 重新设定你想要的版本。

• 问题： pyenv 命令本身找不到。

  • 原因： 你的环境变量 Path 设置错了。
  • 解决： 回到本文的第3步，仔细检查 Path 中是否包含 shims 和 bin 目录，并且它们在最顶端。

希望这份文档能成为你未来使用 pyenv 的得力助手！