pyenv本质是Python解释器调度层，非单纯多版本安装工具；它通过shims机制拦截python等命令调用，依赖PATH中$HOME/.pyenv/shims前置及eval "$(pyenv init -)"正确执行，缺一不可。
pyenv 不是“装多个 Python”的工具，而是让每个项目用对版本、互不干扰的解释器调度层。它不改系统 Python，也不靠虚拟环境隔离——它直接接管 python 命令的执行路径。能不能用好，关键不在装了多少版本，而在 shell 能否正确识别并拦截调用。
pyenv 命令找不到？PATH 和 eval 缺一不可
最常见的情况是：明明执行了安装脚本，但终端敲 pyenv 就报 command not found。这不是安装失败，而是 shell 根本没加载它。
-
$HOME/.pyenv/bin必须出现在$PATH的**前段**，不能只追加在末尾；否则系统会优先找到系统自带的python或其他同名命令 -
eval "$(pyenv init -)"这行必须执行，它会把$HOME/.pyenv/shims加入PATH——这才是真正拦截python、pip等命令的入口目录 - Zsh 用户注意：
pyenv init -默认输出 Bash 语法，要显式写成pyenv init - zsh；Bash 用户同理用pyenv init - bash - 改完配置文件（如
~/.zshrc）后，必须source ~/.zshrc或新开终端，exec $SHELL也行，但别只靠关掉再打开 iTerm —— 有些 GUI 终端不会重读配置
pyenv install 失败？先看系统依赖和镜像源
pyenv install 3.12.4 卡住或报编译错误，90% 以上不是 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：确认
xcode-select --install已执行，Homebrew 安装的pyenv不自动带编译链 - 国内用户务必设镜像源，否则经常超时：
export PYTHON_BUILD_MIRROR_URL=https://npmmirror.com/mirrors/python，加到~/.zshrc并source - 如果某版本 tar.xz 已手动下载，可放进
$(pyenv root)/cache/目录，pyenv install会自动复用，跳过下载
python --version 还是系统版？你还没指定作用域
pyenv 默认不接管任何命令——它只在你明确设置后才生效。没设置，就永远走系统路径。
立即学习“Python免费学习笔记（深入）”；
- 全局生效：
pyenv global 3.12.4，所有新终端都用这个版本（慎用，可能影响系统工具） - 项目级生效：
pyenv local 3.9.18，会在当前目录生成.python-version文件，cd 进来自动切换 - 临时会话：
pyenv shell 3.8.10，仅当前终端有效，关闭即失效，适合快速验证 - 验证是否真生效？别只信
python --version，一定要跑which python——正确路径应是$HOME/.pyenv/shims/python，而不是/usr/bin/python或/opt/homebrew/bin/python
Windows 上用 pyenv-win？环境变量名和路径顺序是命门
Windows 版叫 pyenv-win，行为类似但配置逻辑不同：它不靠 shell 初始化，而靠 Windows 环境变量驱动。
- 必须同时设置三个变量：
PYENV_ROOT（指向pyenv-win安装根目录）、PYENV_HOME（通常为PYENV_ROOT的父级）、PYENV（值为%PYENV_ROOT%\bin） -
Path中必须包含两条路径：%PYENV_ROOT%\bin和%PYENV_ROOT%\shims，且shims要排在bin**之前**——因为拦截逻辑靠 shims 目录里的同名脚本实现 - PowerShell 用户注意：
pyenv-win的初始化脚本需通过Invoke-WebRequest下载并执行，不能直接用 curl；安装后建议重启 CMD/PowerShell，而非仅source
真正卡住人的从来不是“怎么装”，而是“为什么没生效”。pyenv 的 shims 机制很轻，但也因此极其依赖 shell 环境的精确配置——少一行 eval，或多一个错位的 Path 条目，整个链条就断了。
