pyenv的核心价值是让不同项目使用正确的Python版本且互不干扰，它不修改系统Python，也不依赖虚拟环境，而是直接管理解释器本身；安装后shell配置不生效或pyenv命令找不到，主因是未正确将$HOME/.pyenv/bin加入PATH前段、未在对应shell配置文件中执行eval "$(pyenv init -)"以注入shims路径。
pyenv 的核心价值不是“装多个 Python”，而是“让不同项目用对的 Python 版本，且互不干扰”。它不碰系统 Python，也不依赖虚拟环境，直接管理解释器本身。
安装后 shell 配置不生效，pyenv 命令找不到
这是最常见卡点：安装完没 reload shell 或配置写错位置。关键不是“装了”，而是“shell 能否在 PATH 中找到 pyenv”。
-
pyenv二进制默认放在$HOME/.pyenv/bin/pyenv，必须确保该路径在$PATH前段 - 配置要写进你当前 shell 的启动文件（
~/.bashrc、~/.zshrc或~/.bash_profile），不是随便哪个文件 -
eval "$(pyenv init -)"这行必须执行，它会动态注入 shim 目录（如$HOME/.pyenv/shims）到PATH，否则python命令不会被拦截切换 - Zsh 用户注意：
pyenv init -默认输出 Bash 语法，需显式指定pyenv init - zsh；Bash 用户同理用pyenv init - bash
pyenv install 3.12.4 失败：编译报错或网络超时
失败主因是缺失系统依赖或下载源被墙，不是 pyenv 本身问题。
- Ubuntu/Debian 系统务必先装全编译工具链：
sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev - macOS 用 Homebrew 安装后，还需确认 Xcode Command Line Tools 已就绪：
xcode-select --install - 国内用户建议设置镜像源避免超时：
export PYTHON_BUILD_MIRROR_URL=https://npmmirror.com/mirrors/python（加到~/.bashrc并source） - 如果已下载过某版本的 tar.xz 包，可手动放到
$(pyenv root)/cache/下，pyenv install会自动识别复用
为什么 python --version 还是系统自带版本？
因为没设置任何版本作用域，pyenv 默认不接管 python 命令——它只在你明确指定后才介入。
立即学习“Python免费学习笔记（深入）”；
- 全局生效：运行
pyenv global 3.12.4，所有新终端都会用这个版本 - 项目级生效：进入项目目录，运行
pyenv local 3.9.18，会在当前目录生成.python-version文件，cd 进来自动切换 - 临时会话：运行
pyenv shell 3.8.10，仅当前终端生效，关闭即失效 - 验证是否生效：别只信
python --version，用which python看路径——正确时应指向~/.pyenv/shims/python，而非/usr/bin/python
和 venv / virtualenv 是什么关系？
pyenv 管解释器，venv 管包，二者正交，常配合使用。不要试图用 pyenv 替代虚拟环境。
-
pyenv安装的每个 Python 版本，其pip默认安装包都在各自site-packages下，天然隔离——但这只是解释器层隔离，不是项目层 - 同一 Python 版本下多个项目仍会共享包，所以推荐组合：
pyenv local 3.11.9+python -m venv .venv - 如需自动集成虚拟环境，可装插件
pyenv-virtualenv，但非必需；纯pyenv已足够解决“版本错配”这个最硬的痛点
真正容易被忽略的是：.python-version 文件会被 Git 跟踪，也会影响子目录行为；如果你在父目录设了 local 版本，而子项目需要另一个版本，得在子目录里再跑一次 pyenv local 覆盖——pyenv 的作用域是继承+覆盖，不是绝对路径绑定。
