多版本管理
入门篇假设本机已有一个可用的 Python 3.10+。实际工作里常要 同时保留多个解释器版本（例如本机 3.10，某仓库要 3.12，CI 矩阵测 3.10–3.13）。
本篇讲 解释器版本 怎么装、怎么切、项目怎么钉死。它和「虚拟环境」不同：venv 是在 某一个 Python 之上隔离包装；多版本是先解决「用哪一个 Python」。
与依赖管理的关系见「项目与包管理」；单版本下的 venv 见「类型提示与虚拟环境」。
先分清两件事
| 概念 | 解决什么 | 例子 |
|---|---|---|
| Python 多版本 | 机器上 有哪些解释器（3.10 / 3.11 / 3.12…） | python3.11、pyenv、uv python |
| 虚拟环境 | 同一解释器下，项目依赖互不污染 | .venv/、conda env |
典型顺序：选对 Python 版本 → 再为该版本建虚拟环境 → 再装依赖。
很多时候版本也不是你说了算：仓库的 requires-python、.python-version、Dockerfile、CI matrix 才是约束。
为什么需要多版本
- 不同项目声明了不同的
requires-python - 要复现线上/同事的小版本差异（补丁级有时也要命）
- 库作者要在多个版本上跑测试（tox / nox / CI matrix）
- 系统自带 Python 太旧或不能乱动（尤其 Linux）
现场信号：项目钉了哪个版本
| 信号 | 含义 |
|---|---|
requires-python = ">=3.10"（pyproject.toml） | 允许的版本范围 |
.python-version | 工具（pyenv / uv 等）优先用的具体版本 |
runtime.txt / 平台特定文件 | 部分 PaaS 用 |
Dockerfile FROM python:3.12-slim | 运行时以镜像 为准 |
CI python-version: ["3.10", "3.12"] | 要兼容的测试矩阵 |
Conda environment.yml 里的 python=3.11 | Conda 环境自带解释器版本 |
接手项目：先看这些，再装对应解释器；不要只用本机默认 python3「碰巧能跑」就完事。
常见方案（都会遇到）
1. 系统 / 官方安装包并排
- macOS：
brew install python@3.11等，命令常为python3.11 - Windows：官网安装包可装多版；
py启动器 可py -3.11 - Linux：发行版包，或 deadsnakes 等第三方源（注意信任与升级策略）
特点：简单；版本一多，PATH 谁优先容易乱。适合「就多两个版本」的轻度需求。
2. pyenv（经典多版本工具）
专门管「装多个 Python + 按目录切换」：
pyenv install 3.12.7
pyenv global 3.12.7 # 用户默认
pyenv local 3.11.9 # 当前目录写入 .python-version
python -V # 应显示被选中的版本
特点：存量教程与项目多；与 venv/pip 搭配常见。进了用 pyenv 的团队，跟 .python-version 即可。
3. uv 管理 Python 版本（绿场友好）
uv 不但管包，也能安装与选择解释器：
uv python install 3.10 3.11 3.12
uv python list
uv python pin 3.12 # 写入 .python-version
uv sync # 按钉死的版本建/用环境
uv run python -V
特点：与本站推荐的项目流一体；不必先装系统 Python 也能拉解释器。存量若全员已用 pyenv，不必强行改。
4. asdf / mise 等通用版本管理器
用插件同时管 Node、Python、其他运行时。团队若统一 asdf/mise，Python 插件那套规则优先。
5. Conda / Mamba
环境里直接带指定 Python：
# environment.yml 片段
dependencies:
- python=3.11
- numpy
数据科学仓库很常见：解释器版本与包 一起由 Conda 管。此时不必再叠一套 pyenv，除非文档明确要求。
6. 容器镜像（团队/生产真相源）
很多服务以 Docker 里的 python:3.x 为准。本机多版本是为了开发体验；部署以镜像/CI 为准。本地可用同主版本的解释器 + venv 贴近开发。镜像与 Compose 通识见工程实践「Docker 基础」。
你不能做主时
- 按仓库的
.python-version/requires-python/ CI / Dockerfile 安装 - 用项目指定的版本管理器（有则用；没有再用系统多版本）
- 虚拟环境必须建在 正确主版本 上（3.10 的 venv 不能假装成 3.12）
- 不要把「我全局装了最新 Python」当成所有项目的默认
你能做主时（本机与绿场）
本站建议：
- 用 uv（或团队已采用的 pyenv）在本机保留 3.10 / 3.11 / 3.12 等需要的版本
- 每个项目：
uv python pin或 pyenvlocal，提交.python-version（若团队同意） pyproject.toml写清requires-python- 仍为每个项目建独立虚拟环境（版本对 + 依赖隔离）
uv python install 3.12
uv init my-app && cd my-app
uv python pin 3.12
uv add requests
uv run python -V
与虚拟环境、包管理怎么配合
多版本工具选出 python3.12
↓
创建 .venv（基于 3.12）
↓
pip / uv / Poetry … 安装依赖
| 错误做法 | 问题 |
|---|---|
只用系统 Python，到处 sudo pip | 污染系统、升级翻车 |
版本换了但旧 .venv 还在用 | 解释器路径失效或行为怪异；应重建 venv |
requires-python 写 >=3.10，本机却从未用 3.10 测过 | CI 一跑才发现不兼容 |
升级项目主版本时：改 pin / requires-python → 删掉旧 .venv 再 sync/install → 跑测试。
测试多个版本（库/工具作者）
- CI matrix（GitHub Actions
strategy.matrix.python-version等）是主流 - 本机可用 tox / nox，或
uv python install多个版本后分别uv sync --python 3.11之类做抽查 - 应用服务通 常 钉一个运行时版本 即可；库才更需要矩阵
决策简表
| 情境 | 常见做法 |
|---|---|
| 团队已有 pyenv / asdf / Conda | 跟团队 |
| 绿场 + 已用 uv 管依赖 | uv python 一并管解释器 |
| 只是本机多装两三个版本 | brew / 官网安装包 / py -3.x 也可 |
| 生产 | 镜像或运行平台钉死；不依赖开发机 PATH |
遗留只写了 python3 | 读 CI；补上 requires-python 与文档 |
要点
- 多版本 ≠ 虚拟环境：先选解释器，再隔离依赖
- 存量项目看
.python-version/requires-python/ CI / 镜像，而不是个人默认 Python - 经典工具：系统并排安装、pyenv、uv python、asdf/mise、Conda、容器
- 绿场可与包管理一起用 uv；换主版本后重建虚拟环境
- 应用钉版本求稳；库才重点做多版本测试矩阵