核心是构建可隔离、可复现、不干扰系统的开发机制：用pyenv管理多版本Python解释器，venv隔离项目依赖，配合Homebrew和xcode-select搭建安全基础工具链。
macos 上配置 python 开发环境，核心不是装一个 python，而是建立一套可隔离、可复现、不干扰系统的协作机制。系统自带的 python 是“只读配件”，homebrew 装的 python 容易混入全局路径，真正稳妥的做法是用 pyenv 管版本 + venv 或 conda 管环境，二者分工明确：pyenv 负责切换解释器（比如 3.8/3.11/3.12），venv/conda 负责隔离包依赖。
先装基础工具链：xcode-select 和 Homebrew
打开终端，执行两步初始化：
- xcode-select --install：安装命令行开发工具（make、clang、git 等），这是后续编译 Python 源码的前提
- brew install pyenv：用 Homebrew 安装 pyenv（不推荐直接 pip install pyenv）
接着把 pyenv 加入 shell 初始化文件（macOS Catalina 及以后默认用 zsh，编辑 ~/.zshrc）：
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"
保存后运行 source ~/.zshrc 生效。验证：输入 pyenv --version 应有输出。
用 pyenv 安装并管理多个 Python 版本
pyenv 不会动系统 Python，所有版本都装在 ~/.pyenv/versions/ 下，完全用户级隔离：
立即学习“Python免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 查看可用版本：pyenv install --list | grep "3\.[1-2][0-9]"（筛选较新稳定版）
- 安装指定版本（例如 3.11.9）：pyenv install 3.11.9
- 设为当前目录默认版本：pyenv local 3.11.9（会在项目根目录生成 .python-version 文件）
- 设为全局默认（慎用）：pyenv global 3.11.9
执行 python --version 即可看到生效的版本。注意：此时 python 和 python3 指向同一解释器，不会出现“python 指 conda、python3 指系统”的错乱问题。
为每个项目创建独立虚拟环境
有了干净的 Python 解释器，下一步是用内置 venv 创建轻量隔离环境（比 conda 更简洁，适合纯 Python 项目）：
- 进入项目目录，运行：python -m venv .venv（推荐用 .venv 命名，VS Code 默认识别）
- 激活：source .venv/bin/activate（提示符前会出现 (.venv)）
- 此时 pip install 的包只存在于该环境，which python 返回的是 project/.venv/bin/python
- 退出：deactivate
建议在项目根目录保留 requirements.txt：pip freeze > requirements.txt，他人克隆后只需 python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt 即可复现环境。
VS Code 中正确识别和使用虚拟环境
VS Code 不会自动激活 shell 中的虚拟环境，需手动指定解释器路径：
- 按 Cmd+Shift+P 打开命令面板，输入 Python: Select Interpreter
- 在列表中选择 ./.venv/bin/python（或点击 “Enter interpreter path…” 手动定位）
- 确认后，右下角状态栏会显示当前解释器路径；新建终端（Terminal → New Terminal）也会自动激活该环境
- 如需调试，确保 launch.json 中的 python 字段未硬编码路径，保持默认即可
若 VS Code 提示 “ModuleNotFoundError”，大概率是解释器选错或未激活 —— 此时不要 pip install -g，而是检查是否选对了 .venv/bin/python。
