UV 工具安装与国内镜像源配置指南

概述

UV 是由 Astral 团队开发的高性能 Python 包管理器和解析器，旨在提供比传统工具更快的依赖解析和安装体验。本文档提供 UV 的安装指南及国内镜像源配置方法。

系统要求

支持的操作系统：Windows 10+/macOS 10.15+/Linux (glibc 2.31+)
Python 版本：无需预先安装 Python（UV 自带 Python 环境管理）

安装方法

推荐方案：使用官方安装脚本

Linux/macOS 系统

base 复制代码

# 执行一键安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 系统

PowerShell 复制代码

# PowerShell 中执行安装命令
irm https://astral.sh/uv/install.ps1 | iex

安装完成后，重启终端并验证安装：

bash 复制代码

uv --version

备选方案：通过 Pipx 安装

bash 复制代码

# 安装 pipx（如尚未安装）
python -m pip install --user pipx
python -m pipx ensurepath

# 通过 pipx 安装 uv
pipx install uv

镜像源配置

临时使用镜像源

通过环境变量临时指定镜像源（仅当前会话有效）：

bash 复制代码

# 使用阿里云镜像源
export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"

# 或使用清华大学镜像源
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple/"

# 安装包（将使用上述镜像源）
uv pip install <package-name>

永久配置镜像源

配置文件路径

Linux/macOS: ~/.config/uv/uv.toml
Windows: %APPDATA%\uv\uv.toml

配置内容

创建或编辑配置文件，添加以下内容：

toml 复制代码

[index]
# 阿里云镜像源
url = "https://mirrors.aliyun.com/pypi/simple/"

# 或使用清华大学镜像源
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

命令行直接指定镜像源

bash 复制代码

# 安装包时直接指定镜像源
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ <package-name>

镜像源列表

提供商	镜像源地址
阿里云	mirrors.aliyun.com/pypi/simple...
清华大学	pypi.tuna.tsinghua.edu.cn/simple/
豆瓣	pypi.doubanio.com/simple/
华为云	repo.huaweicloud.com/repository/...

配置验证与故障排除

验证配置

bash 复制代码

# 检查当前生效的索引URL
uv config get index.url

# 测试包安装速度
uv pip install numpy

常见问题处理

SSL 证书错误
- 确保使用 https:// 前缀而非 http://
配置未生效
- 验证配置文件路径和格式是否正确
- 使用 uv config list 查看所有配置
清除缓存
bash 复制代码
```
uv clean
```

注意事项

UV 的配置独立于 pip，需单独设置镜像源
不同项目的虚拟环境可以单独配置不同的源
定期更新 UV 工具以获取最新功能和安全更新：
bash 复制代码
```
uv self update
```

性能优化建议

选择地理位置最近的镜像源
定期清理缓存：uv clean
对于大型项目，考虑使用 UV 的离线模式

通过以上配置，可显著提升在中国大陆地区的包下载速度，改善开发体验。