UV 换源指南：配置 PyPI 与 CPython 源提升下载速度

二、核心概念：为什么要分'PyPI 源'和'CPython 代理'？

很多人第一次配置 UV 会困惑：为什么要搞两个配置？其实这是因为 UV 的资源获取对应 两个完全独立的场景，互不影响，必须分开配置：

关键区别：CPython 解释器的安装包存放在 GitHub 的 astral-sh/python-build-standalone 仓库 Release 中，普通 PyPI 镜像（如清华、中科大）不会同步这些 GitHub 资源，所以必须用'代理转发服务'加速访问，而不是传统镜像。

三、详细配置：吃透每一个参数

上面的快速配置能满足大部分需求，但了解细节能帮你应对特殊情况（比如代理失效、需要切换源）。

1. CPython 国内镜像配置

配置本质

python-install-mirror 切换为腾讯 cnb 官方同步源（https://cnb.cool/astral-sh/python-build-standalone），满足国内下载 python 需求。

验证是否生效

配置后执行带 --verbose（简写 -v）的安装命令，查看日志中的下载链接：

uv python install 3.12 -v 

2. PyPI 源配置（第三方包下载加速）

PyPI 源是我们熟悉的'镜像'概念，国内有多个稳定的镜像可用，配置也更灵活。

配置格式

采用 [[index]] 数组格式，每个 [[index]] 代表一个 PyPI 镜像源，支持同时配置多个（UV 会按优先级依次尝试下载）。每个源的核心参数：

• name：自定义名称（如 tsinghua、ustc），仅用于识别，无实际功能。
• url：镜像的实际地址（必须是 simple 格式，即路径包含 /simple）。
• default = true：两个关键作用：
  1. 调整优先级：标记为 default 的源会被移到'最低优先级'，UV 会先从非 default 源下载（比如示例中先查清华源，再查中科大源）。
  2. 禁用官方源：只要有一个源标记为 default，UV 就会自动禁用官方 PyPI 源（https://pypi.org/simple），避免国外地址拖慢速度。

国内常用 PyPI 镜像地址

整理了 4 个稳定可用的国内镜像，按需替换：

• 清华：https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple（更新快，推荐首选）
• 阿里：http://mirrors.aliyun.com/pypi/simple（稳定性强，适合阿里云服务器）
• 中科大：https://mirrors.ustc.edu.cn/pypi/simple（学术机构镜像，可靠）
• 兰大：https://mirrors.lzu.edu.cn/pypi/web/simple（西北区域镜像，适合西北用户）

验证是否生效

执行 uv add 命令并加 -v 参数，查看包的下载链接是否来自配置的镜像：

uv add requests -v 

若日志中出现 https://mirrors.tuna.tsinghua.edu.cn/.../requests/... 等这类链接，说明 PyPI 源配置成功。

四、常见问题：解决配置中的小坑

1. 配置后不生效？
   • 检查配置文件路径是否正确（比如 Windows 下是否误写为 %APPDATA%\uv.toml，少了 uv 文件夹）。
   • 检查 python-install-mirror 是否放在 [[index]] 上方。
   • 检查语法错误（如引号缺失、逗号多余，TOML 格式对语法要求严格）。
2. CPython 代理失效？
   • GitHub 加速服务可能会波动，若 ghfast.top 用不了，替换为 ghproxy.com 或其他 GitHub 加速域名（格式不变）。
3. 可以配置多个 default = true 吗？
   • 可以，但多个 default 源会处于同一'最低优先级组'，UV 会随机尝试。官方建议只设一个 default 源，避免逻辑混乱。

五、总结

UV 换源的核心是'分场景配置'：

• 下载 Python 解释器：用 python-install-mirror 配置 GitHub 加速代理，且必须放在 [[index]] 上方。
• 下载第三方包：用 [[index]] 配置国内 PyPI 镜像，通过 default = true 调整优先级并禁用官方源。

按照本文的步骤配置后，无论是安装 Python 解释器还是第三方包，都能体验到 UV 真正的'极速'优势。