说明
本文介绍一套 现代、可复现、团队友好 的 Python 管理方案：
- mise：统一管理 Python 版本（全局 / 项目级）
- uv：管理虚拟环境、依赖、锁文件、运行命令
1️⃣ 部署：安装 mise 与 uv
1.1 安装（推荐 Homebrew）
brew install mise uv
验证安装：
mise --version
uv --version
1.2 让 mise 接管 shell（非常关键）
以 zsh 为例，在 ~/.zshrc 末尾加入：
eval "$(mise activate zsh)"
使配置生效：
source ~/.zshrc
2️⃣ 全局：用 mise 管理 Python 版本
2.1 安装指定 Python 版本
mise install python@3.12
2.2 设置全局默认 Python
mise use -g python@3.12
验证：
python -V
which python
3️⃣ 项目级 Python：.mise.toml
3.1 在项目中固定 Python 版本
进入项目目录：
cd /path/to/your-project
快速写入项目配置：
mise use python@3.12
生成的 .mise.toml 最小内容：
[tools]
python = "3.12"
3.2 启用 Python venv 自动管理（强烈推荐）
[tools]
python = "3.12"
[env]
_.python.venv = { path = ".venv", create = true }
这段配置的效果是：
- 自动创建
.venv/- 自动使用该 venv
- 不需要
source activate- 和
uv run/mise run完美配合
⚠️ 注意：
mise **不会自动生成
[env]**，这一段必须你手动写（或用模板）。
4️⃣ uv：依赖与环境管理
4.1 新项目初始化（可选）
uv init --bare
作用:
- 创建
pyproject.toml- 不会安装依赖
4.2 添加 / 同步依赖（推荐路径）
uv add requests # 写入 pyproject.toml
uv sync # 按 uv.lock 同步环境
升级依赖并更新锁文件：
uv lock --upgrade
4.3.1 从 requirements.txt 迁移
uv add -r requirements.txt
功能
- 从 requirements.txt 迁移依赖
- 写入 pyproject.toml 并生成 uv.lock
4.3.2 仅临时兼容（不推荐长期）
uv pip install -r requirements.txt
功能:
- pip 兼容模式
- 仅安装，不记录依赖
4.4 导出完整依赖
uv export -o requirements.txt
功能:
- 从 uv.lock 导出完整依赖
uv export --no-dev -o requirements.txt
功能:
- 仅导出生产依赖
4.5 运行项目（无需激活 venv）
uv run python -m your_module
uv run pytest
uv run uvicorn app.main:app
5️⃣ venv 里有没有 pip解决
5.1 使用 ensurepip（官方方式）
./.venv/bin/python -m ensurepip --upgrade
./.venv/bin/python -m pip install -U pip
5.2 用 uv 把 pip 装进 venv（推荐）
uv pip install --python ./.venv/bin/python pip
如果你已经在用 uv，这是最简单、最一致的方式。
6️⃣ mise 常用命令速查
6.1 配置位置
~/.config/mise/config.toml # 全局配置
.mise.toml # 项目配置
6.2 常用命令
mise use -g python@3.12 # 全局 Python
mise use python@3.12 # 项目 Python（写入 .mise.toml）
mise install # 安装当前项目所需工具
mise current # 当前生效版本
mise ls # 已安装工具
mise exec -- python -V # 在 mise 环境中执行
mise doctor # 诊断环境问题
7️⃣ uv 常用命令
uv add requests # - 添加依赖到 `pyproject.toml`、生成 / 更新 `uv.lock`、- 安装依赖到当前虚拟环境
uv sync # 根据 `uv.lock` 精确同步虚拟环境、保证本地 / CI / 生产环境一致
uv run cmd # 在项目虚拟环境中运行命令
uv add -r requirements.txt
uv pip install requests # 兼容 pip
uv export -o requirements.txt
uv export --no-dev -o requirements.txt
8️⃣ 依赖文件职责
pyproject.toml ← 声明依赖（人写）
uv.lock ← 锁定依赖（机器写）
requirements.txt ← 可选导出（机器写）