🎯 为什么需要指定 Python 版本？
在真实开发中，指定 Python 版本至关重要：
- 依赖兼容性：某些包仅支持特定 Python 版本
- 团队统一：确保所有开发者使用相同版本
- 生产一致性：避免开发与生产环境版本不一致导致的 Bug
- 多版本测试：验证代码在不同 Python 版本下的表现
🚀 三大场景实战指南
场景一：创建新项目时指定版本（最常用）
在项目初始化阶段指定 Python 版本是最佳实践：
# 方式 1：使用 --python 参数直接指定
uv init --python 3.9
# 这将创建一个使用 Python 3.9 的新项目
# 方式 2：指定精确版本
uv init --python 3.11.5
# 方式 3：使用 conda 环境中的 Python
uv init --python /path/to/your/python
执行后，uv 会：
- 自动检测或下载指定的 Python 版本
- 创建使用该版本的虚拟环境
- 在
pyproject.toml中记录 Python 版本约束
场景二：为现有项目更改 Python 版本
如果你的项目已经创建，但需要更改 Python 版本：
# 1. 首先，删除旧的虚拟环境（重要！）
rm -rf .venv # Linux/macOS
# 或 rmdir /s .venv # Windows
# 2. 使用指定版本重新创建虚拟环境
uv python pin 3.10
# 方法 1：使用 pin 命令
# 或 uv venv --python 3.10
# 方法 2：重新创建 venv
# 3. 重新同步所有依赖
uv sync
重要提示：更改 Python 版本后，某些依赖可能需要重新安装或选择兼容版本。务必运行 uv sync 让 uv 重新解析依赖树。
场景三：多版本管理与系统级设置
对于需要管理多个 Python 版本的高级用户：
# 1. 查看系统可用 Python 版本
uv python list
# 输出示例：
# - cpython-3.12.3 (C:\Users\...\Python\Python312\python.exe)
# - cpython-3.11.9 (C:\Users\...\Python\Python311\python.exe)
# - cpython-3.10.11 (C:\Users\...\Python\Python310\python.exe)
# 2. 安装特定的 Python 版本
uv python install 3.9
uv python install 3.11.8 # 安装精确版本
# 3. 设置项目默认 Python 版本（在项目目录内）
echo 'python = ">=3.10,<3.12"' >> pyproject.toml
📋 在 pyproject.toml 中声明版本约束
除了命令行，你可以在 pyproject.toml 中声明 Python 版本要求，这是团队协作的最佳实践：
# 在 pyproject.toml 的 [project] 部分添加
[project]
name = "my-project"
version = "0.1.0"
# 声明 Python 版本要求
requires-python = ">=3.9,<3.12" # 接受 3.9 到 3.11 的版本
# 或更精确的约束
requires-python = "~3.10.0" # 3.10.x 系列，x>=0
# 或单一版本
requires-python = "==3.11.*" # 3.11 系列的任何版本
当其他人运行 uv sync 时，uv 会检查此约束并尝试使用兼容的 Python 版本。
🔧 高级技巧与疑难解答
1. 如何在服务器上指定版本？
服务器环境与本地类似，但可能需要先安装特定 Python 版本：
# 在 Ubuntu 服务器上
sudo apt update
sudo apt install python3.10 python3.10-venv
# 然后在项目中使用
uv venv --python python3.10
uv sync
2. 版本指定失败怎么办？
# 检查 uv 是否能找到指定版本
uv python find 3.9
# 如果没有，先安装
uv python install 3.9
# 列出所有已安装/可用的解释器
uv python list --all
3. 使用.python-version 文件
像 pyenv 一样，uv 也支持 .python-version 文件：
# 创建版本文件
echo "3.10.11" > .python-version
# uv 会自动使用此版本
uv sync
💡 最佳实践总结
- 项目开始即指定：使用
uv init --python X.Y从一开始就固定版本 - 版本约束明确：在
pyproject.toml中添加requires-python字段 - 锁文件一致性：确保
uv.lock与 Python 版本匹配，不同版本可能需要重新生成 - 团队沟通：在 README 中明确说明项目所需的 Python 版本
- CI/CD 集成：在 CI 配置中明确指定 Python 版本，如 GitHub Actions 的
actions/setup-python@v4
