pyenv可解决mac多python项目版本冲突问题，通过path劫持实现隔离；需用homebrew安装，配置~/.zshrc并source生效；支持global、local、shell三级版本切换，安装时m芯片需先装编译依赖。
您在Mac上同时维护多个Python项目，每个项目依赖的Python版本各不相同，手动修改PATH或反复重装极易导致环境混乱、脚本执行失败甚至系统工具异常；pyenv通过路径劫持机制实现版本隔离，所有安装版本独立于系统Python，切换时仅动态调整shell的$PATH优先级，不改动任何已有文件。
安装pyenv并完成基础配置
打开终端，先确保Homebrew已就绪：若未安装，运行/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"；已安装则直接执行brew update && brew install pyenv。
编辑~/.zshrc（macOS默认shell）：依次追加三行（顺序不可颠倒）——
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -zsh)"
【必须执行source ~/.zshrc后所有命令才生效】。验证是否成功：输入pyenv --version，有输出即表示初始化完成。
安装常用Python版本
列出所有可安装的稳定版：运行pyenv install --list | grep "^[0-9]\+\.[0-9]\+\.[0-9]\+$"，筛选出如3.9.18、3.11.9、3.12.5等带三位数字的正式发行版。
安装两个以上版本以保障兼容性：例如pyenv install 3.9.18 3.11.9 3.12.5。M系列芯片用户需提前安装编译依赖：brew install openssl readline sqlite3 xz zlib，否则安装会卡在zlib报错。
安装过程耗时较长（通常3–8分钟），后台自动下载源码→解压→编译→安装，期间不要关闭终端窗口。
按需切换Python版本
pyenv提供三种作用域明确的切换方式，互不干扰：
方法一：全局默认（影响所有新打开的终端）
执行pyenv global 3.11.9 → 立即生效 → 验证：python --version应返回3.11.9。
方法二：项目局部（仅对该目录及子目录生效）
第一步：进入项目根目录，如cd ~/my-django-app
第二步：运行pyenv local 3.9.18 → 自动生成.python-version文件
第三步：退出该目录再返回，python --version自动变为3.9.18
方法三：当前Shell临时（关闭终端即还原）
运行pyenv shell 3.12.5 → 此后该终端中所有python调用均指向3.12.5 → 关闭窗口即失效。
【注意：pyenv local生成的.python-version文件必须位于项目最顶层目录，且不能被.gitignore忽略，否则CI/CD流程会因找不到版本声明而失败】
验证与排错
任何时候想确认当前实际生效的Python路径：运行which python，正确结果应为~/.pyenv/versions/xxx/bin/python格式，而非/usr/bin/python或/opt/homebrew/bin/python。
若python --version仍显示系统自带2.7或Homebrew安装的3.x，请检查~/.zshrc中eval "$(pyenv init -zsh)"是否拼写错误，新版pyenv必须用-zsh参数，写成-或--zsh均会导致初始化失败。
查看全部已安装版本及当前激活状态：输入pyenv versions，带*号的即为当前有效版本。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
