关键在于让 pyenv shim 机制生效：必须按序在 ~/.zshrc 中写入 export pyenv_root="$home/.pyenv"、export path="$pyenv_root/bin:$path"、eval "$(pyenv init -zsh)"，并确保 shell 为 /bin/zsh，之后通过 pyenv local/global/shell 切换版本，所有命令由 ~/.pyenv/shims/ 动态路由。

要让 macos 的 zsh 正确集成 pyenv 实现多版本 python 管理，关键不是堆砌路径，而是让 pyenv 的 shim 机制生效——所有 python、pip 命令都经由 ~/.pyenv/shims/ 动态路由到对应版本。配置必须精准、顺序不能错。

确认 shell 是 zsh
运行 echo $SHELL，输出应为 /bin/zsh。如果不是，先执行：
chsh -s /bin/zsh，然后重启终端。

写入三行初始化代码到 ~/.zshrc
这三行缺一不可，且顺序固定：

• 第一行声明根目录：export PYENV_ROOT="$HOME/.pyenv"
• 第二行前置 shim 路径（不是 versions 路径）：export PATH="$PYENV_ROOT/bin:$PATH"
• 第三行启用命令拦截：eval "$(pyenv init -zsh)"

⚠️ 注意：用 -zsh 而非 - 或 --，新版 pyenv（2.4+）已明确区分 shell 类型，-zsh 才能生成兼容 zsh 的 shim 加载逻辑。

保存后立即生效：
source ~/.zshrc

验证是否成功：

• pyenv --version 有输出
• which python 返回 ~/.pyenv/shims/python（不是 /usr/bin/python 或 versions/xxx/bin/python）
• python --version 应显示当前激活版本（初始为空，需后续安装并设置）

安装 Python 版本前补依赖（尤其 Apple Silicon）
pyenv 编译需要底层库，否则安装会失败或缺失 ssl 模块：

brew install openssl readline sqlite3 xz zlib tcl-tk

M 系列芯片额外追加：

macOS Local Voice

利用 macOS 原生能力实现本地语音识别与合成。通过 yap (Apple Speech.framework) 进行语音转文字，通过 say + ffmpeg 进行文字转语音。完全离线，无需 API 密钥。具备音质检测与智能选声功能。

下载

echo 'export LDFLAGS="-L/opt/homebrew/opt/zlib/lib -L/opt/homebrew/opt/openssl/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/zlib/include -I/opt/homebrew/opt/openssl/include"' >> ~/.zshrc
source ~/.zshrc

安装并切换版本（不碰 PATH）

• 查看稳定版：pyenv install --list | grep "^[0-9]\+\.[0-9]\+\.[0-9]\+$"
• 安装两个常用版：pyenv install 3.11.9 3.12.5
• 设项目级版本（推荐）：进入项目目录后运行 pyenv local 3.12.5，自动生成 .python-version
• 设全局默认（慎用）：pyenv global 3.11.9

每次切换后，python --version 和 which python 必须同步指向 ~/.pyenv/versions/xxx/bin/python。

不要做的事

• ❌ 不要把 ~/.pyenv/versions/3.12.5/bin 直接加进 PATH
• ❌ 不要用 alias 替代 pyenv 的 shim 路由（如 alias python=...）
• ❌ 不要修改 /usr/bin/python 或系统 Python 软链接

这套配置下，pyenv 控制“用哪个解释器”，PATH 只负责“让 pyenv 本身可执行”，真正的版本路由全由 shim 完成——干净、可逆、无残留。