# PyPI 镜像源配置指南

本文档说明如何在 uv 中配置国内 PyPI 镜像源以加快包下载速度。

## 方法1：项目级配置（已配置 ✓）

在 `pyproject.toml` 中已配置清华源：

```toml
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
name = "tuna"
default = true
```

**优点：** 项目级别配置，团队成员共享，无需额外配置

## 方法2：环境变量配置

### 临时使用（当前终端）

```bash
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
uv add numpy
```

### 永久配置

**macOS/Linux:**

```bash
# 添加到 ~/.zshrc 或 ~/.bashrc
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.zshrc
source ~/.zshrc
```

**Windows (PowerShell):**

```powershell
# 添加到 PowerShell 配置文件
[System.Environment]::SetEnvironmentVariable('UV_INDEX_URL', 'https://pypi.tuna.tsinghua.edu.cn/simple', 'User')
```

## 方法3：命令行参数

每次执行时指定：

```bash
# 添加包
uv add --index-url https://pypi.tuna.tsinghua.edu.cn/simple numpy

# 同步依赖
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 安装
uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple numpy
```

## 常用国内镜像源

### 清华大学（推荐）
- URL: `https://pypi.tuna.tsinghua.edu.cn/simple`
- 特点：速度快，更新及时
- 官网：https://mirrors.tuna.tsinghua.edu.cn/

### 阿里云
- URL: `https://mirrors.aliyun.com/pypi/simple/`
- 特点：稳定性好

### 中国科技大学
- URL: `https://pypi.mirrors.ustc.edu.cn/simple/`
- 特点：教育网友好

### 豆瓣
- URL: `https://pypi.douban.com/simple/`
- 特点：老牌镜像

### 腾讯云
- URL: `https://mirrors.cloud.tencent.com/pypi/simple/`
- 特点：企业级稳定

### 华为云
- URL: `https://mirrors.huaweicloud.com/repository/pypi/simple/`
- 特点：国内覆盖好

## 切换镜像源

如果需要切换到其他镜像源，修改 `pyproject.toml`：

```toml
# 使用阿里云镜像
[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
name = "aliyun"
default = true

# 或使用中科大镜像
[[tool.uv.index]]
url = "https://pypi.mirrors.ustc.edu.cn/simple/"
name = "ustc"
default = true
```

## 配置多个镜像源

可以配置多个源作为备份：

```toml
# 主镜像源
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
name = "tuna"
default = true

# 备用镜像源
[[tool.uv.index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
name = "aliyun"

# PyPI 官方源（作为最后备选）
[[tool.uv.index]]
url = "https://pypi.org/simple"
name = "pypi"
```

## 验证配置

测试镜像源是否生效：

```bash
# 查看当前配置
uv --version

# 安装一个测试包
uv add requests

# 如果速度很快（几秒内完成），说明镜像配置成功
```

## 故障排除

### 如果镜像源不生效

1. 检查 `pyproject.toml` 语法是否正确
2. 尝试删除缓存：`rm -rf ~/.cache/uv`
3. 使用命令行参数强制指定源

### 如果镜像源包不全

某些包可能在镜像源中不存在，可以临时使用官方源：

```bash
uv add --index-url https://pypi.org/simple some-rare-package
```

## 推荐配置

**对于大多数用户：** 使用清华源（已在 pyproject.toml 中配置）

**对于企业用户：** 根据网络情况选择腾讯云或阿里云

**对于教育网用户：** 使用清华或中科大镜像

## 性能对比

| 镜像源 | 国内速度 | 更新频率 | 稳定性 |
|--------|---------|---------|--------|
| 清华大学 | ⭐⭐⭐⭐⭐ | 每5分钟 | ⭐⭐⭐⭐⭐ |
| 阿里云 | ⭐⭐⭐⭐⭐ | 每10分钟 | ⭐⭐⭐⭐⭐ |
| 中科大 | ⭐⭐⭐⭐ | 每5分钟 | ⭐⭐⭐⭐ |
| 豆瓣 | ⭐⭐⭐ | 不定期 | ⭐⭐⭐ |

---

**注意：** 本项目已默认配置清华源，无需额外配置即可使用。
