virtualbox_client/docs/uv使用文档.md

# uv 使用文档

> uv 是一个用 Rust 编写的极速 Python 包管理与工具链管理器，由 Astral 公司（Ruff 作者）开发。  
> 它可替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具。

---

## 目录

1. [简介](#1-简介)
2. [安装与配置](#2-安装与配置)
3. [核心命令速查](#3-核心命令速查)
4. [Python 版本管理](#4-python-版本管理)
5. [虚拟环境管理](#5-虚拟环境管理)
6. [包管理](#6-包管理)
7. [项目工作流](#7-项目工作流)
8. [镜像源配置](#8-镜像源配置)
9. [常见问题](#9-常见问题)

---

## 1. 简介

### 1.1 什么是 uv？

uv 是一个"大一统"的 Python 工具链，具备以下核心能力：

| 功能 | 对应传统工具 |
|------|------------|
| Python 版本安装与管理 | pyenv |
| 虚拟环境创建 | venv / virtualenv |
| 包安装 | pip |
| 依赖锁定 | pip-tools / poetry |
| 工具包运行 | pipx |
| 脚本依赖管理 | 原生支持 |

### 1.2 核心优势

- **极快速度**：比 pip 快 10-100 倍
- **单一二进制**：无需 Python 即可安装 uv
- **兼容性强**：兼容 pip 的工作流和 requirements.txt
- **全面替代**：一个工具解决 Python 环境所有问题

---

## 2. 安装与配置

### 2.1 一键安装（推荐）

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

安装后重启终端或执行：

```bash
source $HOME/.local/bin/env
```

### 2.2 其他安装方式

**macOS (Homebrew):**
```bash
brew install uv
```

**Linux (apt/手动):**
```bash
# 下载二进制
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2.3 验证安装

```bash
uv --version
# 输出示例: uv 0.11.11 (x86_64-unknown-linux-gnu)
```

### 2.4 配置国内镜像源（加速）

创建配置文件 `~/.config/uv/uv.toml`：

```toml
# Python 版本下载镜像源
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

# pip 包下载镜像源（阿里云）
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true
```

也可通过环境变量临时设置：

```bash
export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"
```

---

## 3. 核心命令速查

| 命令 | 说明 |
|------|------|
| `uv python install <版本>` | 安装指定 Python 版本 |
| `uv python list` | 列出可用的 Python 版本 |
| `uv venv` | 创建虚拟环境 |
| `uv pip install <包>` | 安装 Python 包 |
| `uv pip sync requirements.txt` | 同步依赖 |
| `uv run <文件>` | 在虚拟环境中运行脚本 |
| `uv add <包>` | 向项目添加依赖 |
| `uv lock` | 生成锁定文件 |
| `uv tool run <工具>` | 运行工具包（类似 pipx） |
| `uv init` | 初始化新项目 |
| `uv build` | 构建分发包 |

---

## 4. Python 版本管理

### 4.1 查看可安装的 Python 版本

```bash
# 列出所有可下载的版本
uv python list --only-downloads

# 列出已安装的版本
uv python list
```

### 4.2 安装指定 Python 版本

```bash
# 安装最新 Python 3.12
uv python install 3.12

# 安装具体版本
uv python install 3.11.11

# 安装多个版本
uv python install 3.10 3.11 3.12
```

### 4.3 查看与切换当前 Python

```bash
# 查看当前使用的 Python
uv python

# 查找特定版本的路径
uv python find 3.11

# 为项目固定 Python 版本
uv python pin 3.12
```

### 4.4 卸载 Python 版本

```bash
# uv 安装的 Python 存储在 ~/.local/share/uv/python/
# 直接删除对应目录即可
rm -rf ~/.local/share/uv/python/cpython-3.10*
```

---

## 5. 虚拟环境管理

### 5.1 创建虚拟环境

```bash
# 在当前目录创建 .venv（使用默认 Python）
uv venv

# 指定 Python 版本创建
uv venv --python 3.12

# 指定名称
uv venv myenv
```

### 5.2 激活虚拟环境

```bash
# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate
```

> **提示**：uv 会自动检测并使用当前目录下的 `.venv`，无需手动激活也可通过 `uv run` 使用。

### 5.3 删除虚拟环境

```bash
# 直接删除 .venv 目录即可
rm -rf .venv
```

---

## 6. 包管理

uv 兼容 pip 的全部功能，且速度更快。

### 6.1 安装包

```bash
# 安装单个包
uv pip install requests

# 安装指定版本
uv pip install "flask>=2.0"

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 从 pyproject.toml 安装
uv pip install -e .
```

### 6.2 管理已安装的包

```bash
# 列出已安装的包
uv pip list

# 查看包信息
uv pip show requests

# 检查依赖冲突
uv pip check

# 卸载包
uv pip uninstall requests
```

### 6.3 依赖锁定

```bash
# 根据 requirements.in 编译出锁定文件
uv pip compile requirements.in -o requirements.txt

# 同步环境到锁定状态
uv pip sync requirements.txt
```

---

## 7. 项目工作流

### 7.1 初始化新项目

```bash
# 创建新项目
uv init my_project
cd my_project

# 添加依赖
uv add requests flask

# 安装所有依赖
uv sync

# 运行项目
uv run python main.py
```

### 7.2 脚本依赖管理（Shebang 方式）

在 Python 脚本顶部添加内联元数据，自动管理依赖：

```python
# /// script
# dependencies = [
#   "requests>=2.28",
#   "rich>=13.0",
# ]
# ///
import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.status_code)
```

运行方式：
```bash
uv run script.py
```

> uv 会自动创建隔离环境并安装依赖，无需手动管理！

### 7.3 工具包管理（替代 pipx）

```bash
# 安装工具包
uv tool install ruff

# 运行工具（无需安装）
uv tool run black --help

# 列出已安装的工具
uv tool list

# 升级工具
uv tool upgrade ruff

# 卸载工具
uv tool uninstall ruff
```

---

## 8. 镜像源配置

### 8.1 配置文件方式

编辑 `~/.config/uv/uv.toml`：

```toml
# ========== Python 版本下载镜像 ==========
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

# ========== 包下载镜像源 ==========
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

# 可配置多个备用镜像源
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
```

### 8.2 环境变量方式

```bash
# Python 版本下载镜像
export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"

# 包下载镜像（临时覆盖）
export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"
```

### 8.3 常用国内镜像源

| 镜像源 | Python 版本镜像 URL | PyPI 镜像 URL |
|--------|-------------------|--------------|
| 华为云 | `https://repo.huaweicloud.com/python` | `https://mirrors.huaweicloud.com/repository/pypi/simple` |
| 阿里云 | - | `https://mirrors.aliyun.com/pypi/simple/` |
| 清华大学 | `https://mirrors.tuna.tsinghua.edu.cn/python` | `https://pypi.tuna.tsinghua.edu.cn/simple/` |
| 中科大 | `https://mirrors.ustc.edu.cn/python` | `https://pypi.mirrors.ustc.edu.cn/simple/` |

---

## 9. 常见问题

### Q1: 安装时遇到权限问题？

```bash
# 确保 ~/.local/bin 在 PATH 中
export PATH="$HOME/.local/bin:$PATH"
```

### Q2: 如何更新 uv？

```bash
uv self update
```

### Q3: uv 和 pip 能否共存？

完全可以。uv 兼容 pip 的工作流，两者可共存使用。建议逐步迁移到 uv。

### Q4: 如何查看帮助？

```bash
# 通用帮助
uv help

# 子命令帮助
uv python --help
uv pip --help
```

### Q5: 如何卸载 uv？

```bash
# 删除二进制文件
rm ~/.local/bin/uv ~/.local/bin/uvx

# 删除配置
rm -rf ~/.config/uv

# 删除缓存
rm -rf ~/.cache/uv

# 删除安装的 Python 版本
rm -rf ~/.local/share/uv
```

### Q6: 为什么我执行 `uv python install` 下载很慢？

请检查是否已配置国内镜像源（参见第 8 节），或手动设置：

```bash
export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"
```

---

## 参考资源

- [uv 官方文档](https://docs.astral.sh/uv/)
- [uv GitHub 仓库](https://github.com/astral-sh/uv)
- [华为云 Python 镜像](https://repo.huaweicloud.com/python)
- [阿里云 PyPI 镜像](https://mirrors.aliyun.com/pypi/simple/)