---
## 0. 先搞懂：uv 是什么
uv 可以理解为：把你常用的这些工具整合并提速了：
- pip（安装包）
- venvvirtualenv（虚拟环境）
- pip-tools（锁依赖）
- pyenv（部分 Python 版本管理能力）
- pipx（全局工具安装）
核心价值：**快、统一、可复现**。
---
## 1. 从零安装
> 官方推荐安装方式（Linux/macOS）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Windows 用 PowerShell（看官方安装页）即可。安装后先确认：
```bash
uv --version
```
---
## 2. 第一条优雅原则：先用“项目模式”，少直接 pip install
### 新建项目
```bash
uv init myproj
cd myproj
```
### 添加依赖
```bash
uv add requests
uv add --dev pytest ruff
```
### 运行代码（重点）
```bash
uv run python main.py
uv run pytest
```
uv run 会自动在正确环境里执行，避免“我到底激活了哪个 venv”这种经典混乱。
---
## 3. 第二条优雅原则：把依赖“锁住”
- uv 会生成 uv.lock（锁文件）
- 把 uv.lock 提交到 Git
- 团队统一用：
```bash
uv sync --frozen
```
这样每个人装出来的版本一致，CI 也稳定。
---
## 4. 第三条优雅原则：工具和项目依赖分开
### 项目依赖（放在项目里）
用 uv add。
### 全局 CLI 工具（如 ruff, black, httpie）
用：
```bash
uv tool install ruff
uv tool run ruff --version
```
临时运行可用：
```bash
uvx ruff check .
```
> 思路：**不要污染全局 Python site-packages**。
---
## 5. 第四条优雅原则：能 uv run 就别手动激活 venv
虽然可以：
```bash
uv venv
source .venv/bin/activate
```
但更推荐直接：
```bash
uv run python xxx.py
```
好处：脚本、CI、Makefile 都更稳定，不依赖 shell 状态。
---
## 6. 第五条优雅原则：Python 版本要明确
- 在 pyproject.toml 写清楚 requires-python
- 团队固定主版本（如 3.11/3.12）
- CI 中同样固定版本
这样能避免“我本地是 3.12，线上是 3.10”的隐形雷。
---
## 7. 常用命令速查（最实用）
```bash
uv init # 初始化项目
uv add <pkg> # 加依赖
uv add --dev <pkg> # 加开发依赖
uv remove <pkg> # 移除依赖
uv sync # 按 lock 安装环境
uv lock # 更新 lock
uv run <cmd> # 在项目环境运行命令
uv tree # 查看依赖树
uv pip install ... # pip 兼容模式（过渡用）
uv tool install <tool> # 安装全局工具
uvx <tool> ... # 临时运行工具
```
---
## 8. CI/CD 优雅用法（非常关键）
在 CI 里推荐：
1. 缓存 uv 的下载缓存目录
2. 使用 uv sync --frozen
3. 所有命令都走 uv run
例如：
```bash
uv sync --frozen
uv run pytest
uv run ruff check .
```
---
## 9. 从 pip 迁移到 uv 的实用路线
### 旧项目有 requirements.txt
可先保持不动，用：
```bash
uv pip install -r requirements.txt
```
然后逐步迁移到 pyproject.toml + uv.lock（推荐最终状态）。
---
## 10. 常见坑（避坑清单）
1. **把 uv.lock 忽略提交** → 团队版本漂移
2. **开发命令不用 uv run** → 本地/CI 行为不一致
3. **工具和项目依赖混装** → 环境越来越脏
4. **不写 Python 版本约束** → 升级后随机炸
5. **频繁手改依赖版本但不更新 lock** → “我这能跑你那不能”
---
## 11. 一套“优雅默认工作流”（可直接照抄）
```bash
uv init
uv add fastapi
uv add --dev pytest ruff
uv run ruff check .
uv run pytest
git add pyproject.toml uv.lock
git commit -m "init with uv"
```
后续新增依赖就 uv add，跑项目就 uv run，部署就 uv sync --frozen。
---