一、 初始问题：pip 命令无法识别

在安装好 pyenv-win 并通过它安装了 Python 3.12.8 之后，我在命令行敲下 pip --version，得到：

'pip' 不是内部或外部命令，也不是可运行的程序或批处理文件。

这通常是环境变量 Path 没有正确配置的典型症状。pyenv 的工作原理就是通过巧妙地修改 Path 路径，让我们使用的命令（如 python, pip）指向它所管理的版本。如果这个环节出错，系统自然找不到命令。

二、 核心关键：正确配置环境变量

经过排查，我发现问题正出在环境变量的配置上。

第1步：打开环境变量编辑器

  • 按下 Win 键，搜索“编辑系统环境变量”，并打开它。

  • 在弹出的窗口中，点击“环境变量...”按钮。

第2步：设置 PYENV 变量 这是为了让系统知道你的 pyenv-win 安装在哪里。

  • 在下方的“系统变量”区域，找到名为 PYENV 的变量。

  • 如果它不存在，就点击“新建”：

    • 变量名: PYENV

    • 变量值: C:\.pyenv\pyenv-win （注意：这里必须替换成你自己电脑上 pyenv-win 的实际安装路径！）

  • 如果它已存在，确保其值是你正确的安装路径。

第3步：编辑 Path 变量（重要）

  • 在“系统变量”区域，找到并选中 Path，然后点击“编辑”。

  • 在弹出的列表中，必须确保下面这两行存在。如果不存在，请点击“新建”来添加它们：

    %PYENV%\shims
%PYENV%\bin

    (这里的 %PYENV% 会自动引用你在上一步设置的路径)

可选

  • 调整顺序，选中 %PYENV%\shims 和 %PYENV%\bin 这两行，将它们移动到列表的 最顶部。这确保了系统会优先使用 pyenv 所管理的 Python 版本，而不是系统中可能存在的其他任何 Python 版本。

第4步：保存并重启命令行

  • 在所有设置窗口上，一路点击“确定”来保存更改。

  • 必须关闭你当前所有的命令行窗口（CMD, PowerShell 等），然后重新打开一个新窗口，这样新的环境变量才会生效。

第5步：验证配置

  • 在新打开的命令行里，运行：

    pyenv --version # 应该显示 pyenv 的版本号
pip --version   # 应该显示当前 pyenv 激活的 python 版本的 pip 信息

    如果这两条命令都能成功运行，恭喜你，基础环境已经配置完美！

三、 pyenv 的核心魅力：自由切换Python版本

环境配置好后，我们就可以体验 pyenv 最强大的功能了。

1. 查看与安装

  • 查看所有可安装的版本：

    pyenv install --list

  • 安装一个新版本 (例如 3.10.11):

    pyenv install 3.10.11

2. 查看与切换

  • 查看本地已安装的所有版本：

    pyenv versions

    输出结果中，带星号 * 的表示当前激活的版本。

  • 切换版本的三种方式（核心功能）： pyenv 切换版本的逻辑有明确的优先级：shell > local > global。

    • pyenv global <版本号> (设置全局默认) 这是最常用的命令，它会设置一个全局默认的 Python 版本。除非有特殊设置，否则所有项目都将使用这个版本。

      pyenv global 3.10.11

    • pyenv local <版本号> (设置项目专用) 这个命令会在当前目录下创建一个名为 .python-version 的文件，内容就是你指定的版本号。只要你的命令行位于这个目录或其子目录中，pyenv 就会自动切换到该版本。这对于管理不同项目依赖不同 Python 版本的情况极为有用。

      # 进入你的项目文件夹
cd D:\my_projects\project_A
# 为该项目设置专用版本
pyenv local 3.8.10

    • pyenv shell <版本号> (设置临时会话) 这个命令只对当前的命令行窗口有效，一旦关闭窗口，设置就会失效。非常适合进行一些临时性的测试。

3. 刷新“垫片” (rehash) 在安装完一个新版本或者安装了带可执行文件的包（如 pipx）之后，运行 pyenv rehash 是个好习惯。它能确保 pyenv 正确创建所有命令的快捷方式（称为 shims 或垫片）。

pyenv rehash

四、 常见问题排查：global 设置为何不生效？

这是一个非常经典的进阶问题。有时你明明执行了 pyenv global 3.13.1，但 pyenv versions 显示当前版本依然是旧的，像这样：

C:\Users\username>pyenv versions
  3.10.11
  3.11.5
* 3.12.8 (set by C:\Users\username\.python-version)
  3.13.1

注意看括号里的提示 (set by C:\Users\username\.python-version)。这说明，在你当前的目录 (C:\Users\username) 下，存在一个 .python-version 文件，这个文件是由之前的 pyenv local 命令创建的。

根据我们前面提到的 local 优先级高于 global 的规则，pyenv 遵守了 local 的设置。

解决方法：

  • 如果你不希望在当前目录有特殊设置，直接删除这个文件即可让 global 设置重新生效：

    del C:\Users\username\.python-version

  • 如果你希望在这个目录下使用新版本，那就用 pyenv local 来覆盖它：

    pyenv local 3.13.1