应采用pyenv+Homebrew组合实现多版本隔离与按需激活：先装Homebrew并配置pyenv，写对zsh初始化三行命令（含-pyenv init -zsh），再安装3.8.20/3.11.9/3.12.5等指定版本，通过pyenv global/local/shell三级作用域精准切换，确保which python指向~/.pyenv/versions/x.y.z/bin/python。
在 macOS 上同时维护图像处理项目（需 Python 3.8.20）、数据爬虫脚本（依赖 3.11.9）和新写的异步服务（要求 3.12.5），却总被系统 Python 冲突、pip 指向错乱、终端新开后版本回退等问题卡住，说明你缺的不是又装一遍 Python，而是一套路径隔离、作用域明确、shell 可感知的版本调度机制。
安装 pyenv 并完成 shell 初始化
打开终端，先确保 Homebrew 已就绪：若未安装，运行 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"；已安装则直接执行 brew update && brew install pyenv。
这一步必须写对顺序，否则 pyenv 命令永远不生效：echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc → echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc → echo 'eval "$(pyenv init -zsh)"' >> ~/.zshrc。
【注意：必须用 -zsh 而非 -，M 系列芯片和新版 macOS 的 zsh 初始化脚本已强制要求该参数，写错会导致 pyenv init 输出为空，后续所有命令都报 command not found】
立即学习“Python免费学习笔记（深入）”；
执行 source ~/.zshrc，再输入 pyenv --version。看到类似 2.4.15 的输出，说明初始化成功。
安装指定 Python 版本并验证可用性
运行 pyenv install --list | grep "^[0-9]\+\.[0-9]\+\.[0-9]\+$" | tail -15 查看最近发布的稳定小版本，避开带字母后缀的预发布版（如 3.12.5rc1）。
Apple Silicon（M 系列）芯片用户安装 3.8 或更老版本时，必须显式指定 OpenSSL 路径，否则编译会卡在 ssl.h: No such file or directory：运行 PYTHON_CONFIGURE_OPTS="--with-openssl=$(brew --prefix openssl@3)" pyenv install 3.8.20。
安装 3.11.9 和 3.12.5 这类较新版本无需额外参数，直接执行 pyenv install 3.11.9 3.12.5，等待编译完成。
输入 pyenv versions，确认输出中包含 3.8.20、3.11.9、3.12.5 且无红色报错信息——此时它们已安静躺在 ~/.pyenv/versions/ 下，互不干扰。
按场景精准切换 Python 版本
pyenv 提供三级作用域，选错层级会导致行为不符合预期：
第一步：设全局默认版本（适用于日常终端命令、CI 脚本等无明确项目上下文的场景）→ 执行 pyenv global 3.11.9 → 新开终端后 python --version 应返回 3.11.9。
第二步：进到图像处理项目根目录 → 运行 pyenv local 3.8.20 → 当前目录下自动生成 .python-version 文件，内容仅为纯文本 3.8.20 → 此时 cd 进入该目录，which python 必须指向 ~/.pyenv/versions/3.8.20/bin/python，而非 system 或 global 路径。
第三步：临时调试一个只在 3.12.5 下复现的 bug → 在任意目录下执行 pyenv shell 3.12.5 → 当前终端窗口内所有 python 调用立即生效，关闭窗口即自动还原，不影响其他会话。
验证切换结果只需两行：python --version 看解释器版本，which python 看真实路径——二者必须严格匹配 ~/.pyenv/versions/x.y.z/bin/python 格式，否则说明某处配置未生效或被其他 alias 覆盖。
