Python版本管理：pyenv多版本切换

认识 pyenv 与安装准备

在开发过程中，不同项目往往依赖不同的 Python 版本，而系统自带的 Python 通常版本固定且升级困难。pyenv 的核心价值在于通过“垫片（shim）”机制实现多版本无缝共存。它并不直接修改系统环境变量，而是在 $PATH 最前端插入一个 ~/.pyenv/shims 目录。当执行 python 命令时，系统会优先命中 pyenv 的 shim 脚本，该脚本会根据当前上下文动态重定向到对应的真实解释器。安装前需确认系统依赖：macOS 需安装 Xcode Command Line Tools 及 brew install pyenv 所需的基础编译工具（如 openssl、readline、zlib）；Linux（如 Ubuntu）需执行 sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python-openssl。此外，必须确保 Shell 环境已正确配置初始化脚本（如 ~/.bashrc 或 ~/.zshrc），以便 pyenv 的自动补全与版本切换功能生效。

安装 Python 多版本并查看版本

完成环境准备后，可通过 pyenv install --list 查看所有可安装的 Python 版本列表。该列表包含官方 CPython、PyPy 以及 Miniconda 等变体。若需安装特定版本，例如 Python 3.10.12，只需执行 pyenv install 3.10.12。安装过程中，pyenv 会自动下载源码并在本地进行编译，耗时取决于网络与 CPU 性能。安装完成后，使用 pyenv versions 命令可列出当前已被 pyenv 接管的所有版本，其中带星号 * 的表示当前激活版本。若需确认安装是否成功，可进入 ~/.pyenv/versions/3.10.12/bin/ 目录查看是否存在 python3 可执行文件。此外，建议首次安装后执行 pyenv rehash（新版 pyenv 通常自动执行）以刷新 shim 索引，确保新安装的版本能被系统正确识别与调用。

切换 Python 版本：全局、目录与临时使用

pyenv 提供三种版本切换机制，其作用域与优先级依次为：pyenv shell（最高，仅当前终端会话有效）> pyenv local（次之，作用于当前目录及子目录）> pyenv global（最低，全局默认）。pyenv global 3.10.12 会修改 ~/.pyenv/version 文件，适用于个人开发机统一基准环境。pyenv local 3.9.16 会在当前目录生成 .python-version 文件，非常适合多项目并行开发，进入该目录即自动切换，离开则恢复。pyenv shell 3.11.4 则通过设置环境变量 PYENV_VERSION 实现临时覆盖，关闭终端即失效。典型工作流为：新建项目目录后，执行 pyenv local 3.10.12，随后创建虚拟环境 python -m venv .venv 并激活。此时所有 pip install 与脚本执行均严格绑定至该版本，彻底避免依赖污染。

验证实际解释器与常见避坑

切换版本后，务必通过组合命令验证实际生效的解释器。执行 python --version 可查看当前版本，但更可靠的方式是 which python 与 pyenv which python。前者应返回 ~/.pyenv/shims/python，后者则指向真实路径如 ~/.pyenv/versions/3.10.12/bin/python。若发现 which python 仍指向 /usr/bin/python，说明 pyenv 未正确接管 PATH。常见原因包括：Shell 配置文件（如 ~/.zshrc）未添加 eval "$(pyenv init -)" 初始化语句，或该语句被其他环境变量覆盖。此时需检查 echo $PATH，确保 ~/.pyenv/shims 位于最前。另一常见坑是系统自带 Python 与 pyenv 冲突，可通过 alias python=python3 或彻底移除系统 Python 的软链接解决。若虚拟环境激活后版本异常，请确认 activate 脚本未被 pyenv shim 拦截，必要时使用 pyenv exec python 强制调用指定版本。