同一台 Mac 上做多个项目时，经常出现“项目 A 要 Python 3.10、项目 B 要 Python 3.12”的情况。如果直接用系统自带 Python 或随手装多个解释器，很容易变成路径混乱、依赖互相污染、换电脑难复现。本文用 pyenv 解决多版本 Python 的安装与切换，用 Poetry 解决依赖与虚拟环境的可重复。
Homebrew 官方说明（可点击）：https://brew.sh/。
安装 pyenv（示例）：
brew install pyenv
然后重开终端，让新安装的软件可被识别。
pyenv 需要在终端启动时被初始化。做法是把初始化配置写进你的 shell 配置文件（zsh 通常是 zshrc）。这里不展开具体编辑器，核心是：确保终端启动后能识别 pyenv，并且 pyenv 的 shims 路径优先于系统路径。
验证是否可用：
pyenv --version
参考链接（可点击）：https://github.com/pyenv/pyenv
安装一个具体版本（示例）：
pyenv install 3.12.2
设置全局默认版本：
pyenv global 3.12.2
进入项目目录后，用本地版本锁定该项目（会生成 .python-version）：
cd /path/to/your-project
pyenv local 3.12.2
检查当前生效解释器：
python -V
which python
Poetry 文档（可点击）：https://python-poetry.org/
若你已具备可用的 pipx，可用它安装 Poetry（示例）：
brew install pipx
pipx install poetry
验证：
poetry --version
建议设置：把虚拟环境放进项目目录，方便 VS Code 识别：
poetry config virtualenvs.in-project true
在项目目录中先锁定 Python 版本，然后获取解释器路径：
pyenv which python
把输出的完整路径复制出来，交给 Poetry（示例路径）：
poetry env use /Users/你的用户名/.pyenv/versions/3.12.2/bin/python
初始化并安装依赖（示例）：
poetry init
poetry add requests
poetry install
运行命令：
poetry run python -V
1) 如果你把虚拟环境放在项目目录，一般会看到 .venv 文件夹，VS Code 选择它即可。
2) 若出现“能运行但提示找不到依赖”，优先确认 VS Code 选的解释器是否与你当前终端一致。
问题 1：切换版本后仍是旧版本
多半是终端未加载 pyenv 初始化配置。重开终端，再检查 which python 是否指向 pyenv 的 shims 或项目环境。
问题 2：Poetry 环境不对
用 poetry env info 查看当前环境，必要时重新执行 poetry env use 并 poetry install。
用 pyenv 管多版本，用 Poetry 管依赖与虚拟环境，再配合项目目录锁定版本，你就能把 macOS 上的 Python 开发环境变得稳定、清晰且可复现。
