# UVM 用户手册

## 目录

1. [简介](#简介)
2. [安装](#安装)
3. [基本使用](#基本使用)
4. [高级功能](#高级功能)
5. [配置文件](#配置文件)
6. [故障排除](#故障排除)
7. [最佳实践](#最佳实践)

## 简介

UVM (UV镜像源管理工具) 是一个专为 UV 包管理器设计的命令行工具，用于管理 Python PyPI 镜像源。它提供以下核心功能：

- 🚀 一键切换镜像源
- ⚡ 自动测速和推荐
- 🌍 内置10+国内镜像源
- ⚙️ 自定义镜像源管理
- 🔍 智能搜索功能
- 🛡️ 配置备份和恢复

## 安装

### 系统要求
- Python 3.9+
- UV 包管理器 (推荐) 或 pip
- 支持 Windows/macOS/Linux

### 安装命令
```bash
pip install uvm
```

## 基本使用

### 查看当前状态

```bash
# 查看当前使用的镜像源
uvm current

# 列出所有可用镜像源
uvm list
```

### 切换镜像源

```bash
# 切换到清华源
uvm use tsinghua

# 切换到阿里云源
uvm use aliyun

# 切换到官方源
uvm use official
```

### 速度测试

```bash
# 测试所有镜像源速度
uvm test

# 获取速度推荐
uvm speedtest
```

## 高级功能

### 自定义镜像源

```bash
# 添加自定义镜像源
uvm add company https://pypi.company.com/simple \
  --description "公司内部镜像源" \
  --region CN

# 查看所有镜像源（包括自定义的）
uvm list

# 删除自定义镜像源
uvm remove company
```

### 搜索功能

```bash
# 搜索包含特定关键词的镜像源
uvm search tsinghua
uvm search 阿里
uvm search US
```

### 配置管理

```bash
# 重置到官方默认源
uvm reset

# 查看详细帮助
uvm --help
uvm use --help
```

## 内置镜像源

| 名称 | URL | 地区 | 推荐指数 |
|------|-----|------|----------|
| tsinghua | https://pypi.tuna.tsinghua.edu.cn/simple | 中国 | ⭐⭐⭐⭐⭐ |
| aliyun | https://mirrors.aliyun.com/pypi/simple | 中国 | ⭐⭐⭐⭐⭐ |
| tencent | https://mirrors.cloud.tencent.com/pypi/simple | 中国 | ⭐⭐⭐⭐ |
| douban | https://pypi.doubanio.com/simple | 中国 | ⭐⭐⭐⭐ |
| huawei | https://repo.huaweicloud.com/repository/pypi/simple | 中国 | ⭐⭐⭐⭐ |
| netease | https://mirrors.163.com/pypi/simple | 中国 | ⭐⭐⭐ |
| sjtu | https://mirror.sjtu.edu.cn/pypi/simple | 中国 | ⭐⭐⭐⭐ |
| bfsu | https://mirrors.bfsu.edu.cn/pypi/simple | 中国 | ⭐⭐⭐ |
| tuna | https://pypi.mirrors.ustc.edu.cn/simple | 中国 | ⭐⭐⭐⭐ |
| official | https://pypi.org/simple | 美国 | ⭐⭐ |

## 配置文件

UVM 管理以下配置文件：

### UV 配置文件
- **Linux/macOS**: `~/.config/uv/uv.toml`
- **Windows**: `%APPDATA%\uv\uv.toml`

UVM 会自动修改此文件来切换镜像源，并创建备份文件。

### UVM 配置文件
- **Linux/macOS**: `~/.config/uv-mirror/config.toml`
- **Windows**: `%APPDATA%\uv-mirror\config.toml`

存储自定义镜像源和用户偏好设置。

### 缓存文件
- **路径**: `~/.cache/uv-mirror/.uvm-cache.json`
- **用途**: 缓存速度测试结果，避免重复测试

## 命令参考

### 全局选项
```bash
--version, -v    显示版本信息
--help, -h       显示帮助信息
```

### 子命令详解

#### `list` - 列出镜像源
```bash
uvm list
```
显示所有可用的镜像源，包括内置和自定义的。

#### `use` - 切换镜像源
```bash
uvm use <name>
```
切换到指定的镜像源。

#### `test` - 速度测试
```bash
uvm test [--cache/--no-cache] [--timeout <seconds>]
```
测试所有镜像源的响应速度。

**选项：**
- `--cache/--no-cache`: 是否使用缓存结果
- `--timeout, -t`: 超时时间（秒）

#### `current` - 当前状态
```bash
uvm current
```
显示当前使用的镜像源信息。

#### `add` - 添加自定义镜像源
```bash
uvm add <name> <url> [--description <text>] [--region <code>]
```
添加一个新的自定义镜像源。

#### `remove` - 删除自定义镜像源
```bash
uvm remove <name>
```
删除指定的自定义镜像源。

#### `search` - 搜索镜像源
```bash
uvm search <query>
```
根据关键词搜索镜像源。

#### `reset` - 重置配置
```bash
uvm reset
```
恢复到官方默认镜像源。

## 故障排除

### 常见问题

#### 1. 命令不存在
```bash
# 确保已正确安装
pip install uvm

# 检查 Python 脚本目录是否在 PATH 中
echo $PATH  # Linux/macOS
echo %PATH% # Windows
```

#### 2. 权限错误
```bash
# 使用用户模式安装
pip install --user uvm

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows
pip install uvm
```

#### 3. 网络连接问题
```bash
# 增加超时时间
uvm test --timeout 10

# 使用代理（如有）
export https_proxy=your-proxy-url
uvm test
```

#### 4. 配置文件损坏
```bash
# 重置配置
uvm reset

# 手动删除配置文件
rm ~/.config/uv/uv.toml  # Linux/macOS
# 或
del %APPDATA%\uv\uv.toml # Windows
```

### 调试技巧

1. **查看详细输出**
```bash
uvm test --verbose
```

2. **检查配置文件**
```bash
# 查看 UV 配置
cat ~/.config/uv/uv.toml

# 查看 UVM 配置
cat ~/.config/uv-mirror/config.toml
```

3. **清理缓存**
```bash
rm ~/.cache/uv-mirror/.uvm-cache.json
```

## 最佳实践

### 1. 选择合适的镜像源
- **国内用户**: 优先选择 tsinghua、aliyun、tencent
- **企业用户**: 考虑添加公司内部镜像源
- **海外用户**: 使用 official 源

### 2. 定期测试速度
```bash
# 每周测试一次速度
uvm test --no-cache
```

### 3. 配置备份
UVM 会自动创建配置备份，但建议定期备份重要配置：
```bash
cp ~/.config/uv/uv.toml.backup uv-config-backup-$(date +%Y%m%d).toml
```

### 4. 在团队中使用
建议团队使用统一的镜像源配置：
```bash
# 在项目中创建 .uvmrc 文件
echo "tsinghua" > .uvmrc

# 团队成员执行
uvm use $(cat .uvmrc)
```

### 5. CI/CD 集成
在持续集成中使用：
```yaml
# GitHub Actions 示例
- name: Setup Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.9'

- name: Install UVM
  run: pip install uvm

- name: Setup mirror
  run: uvm use tsinghua

- name: Install dependencies
  run: uv pip install -r requirements.txt
```

## 进阶用法

### 脚本集成
```bash
#!/bin/bash
# 自动选择最快的镜像源

FASTEST=$(uvm test --no-cache | head -1 | awk '{print $1}')
echo "Fastest mirror: $FASTEST"
uvm use "$FASTEST"
```

### 别名设置
```bash
# bash/zalias
alias uvm-list='uvm list'
alias uvm-use='uvm use'
alias uvm-test='uvm test'
```

### 与其他工具集成
```bash
# 与 pipenv 一起使用
pipenv install uvm
pipenv run uvm use tsinghua

# 与 poetry 一起使用
poetry add uvm
poetry run uvm use tsinghua
```

## 支持与反馈

- 📖 [文档](https://github.com/your-org/uvm#readme)
- 🐛 [问题反馈](https://github.com/your-org/uvm/issues)
- 💬 [讨论区](https://github.com/your-org/uvm/discussions)
- 📧 [邮件支持](mailto:support@example.com)

---

感谢使用 UVM！如果觉得有用，请给我们一个 ⭐️ Star！