UV 换源配置：PyPI 镜像与 Python 解释器加速

PyPI 源和 CPython 代理不是一回事

第一次配 UV 时，最容易混淆的就是这两个入口。它们看起来都在'加速下载'，实际负责的东西完全不同。

这里的关键点是：CPython 解释器安装包在 GitHub 的 astral-sh/python-build-standalone 仓库 Release 里。普通 PyPI 镜像并不会帮你同步这部分内容，所以它们只能管第三方包，管不了解释器本身。这个边界不分清，后面排障会很烦。

参数细节

python-install-mirror

这个配置项的作用很直接：把 Python 解释器下载地址切到国内可用的同步源。示例里用的是腾讯 cnb 的同步地址：https://cnb.cool/astral-sh/python-build-standalone。

配置完以后，可以用 --verbose 或 -v 看实际拉取的地址：

uv python install 3.12 -v 

[[index]]

这是 PyPI 镜像的配置方式。每个 [[index]] 都是一条源，UV 会按顺序尝试。

常用字段就两个：

• name：可选，方便你自己区分来源，不影响功能。
• url：镜像地址，必须是 simple 形式，也就是路径里带 /simple。

default = true 这项有两个效果：一是把这个源放到最低优先级组里，UV 会优先试非 default 源；二是只要存在一个 default 源，官方 PyPI 源 https://pypi.org/simple 就会被自动禁用。这样做的好处很现实，国外源不再参与默认下载，省得拖慢整体速度。

常见的国内 PyPI 镜像

下面这些地址都可以按需替换：

• 清华：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 python install 3.12 -v

装第三方包时也一样：

uv add requests -v

如果输出里出现了你配置的镜像域名，比如 https://mirrors.tuna.tsinghua.edu.cn/.../requests/...，那就说明这部分配置已经接上了。

遇到问题先看这几处

• 配置没生效，先检查文件路径。Windows 很多人会写成 %APPDATA%\uv.toml，少了 uv 目录，UV 根本读不到。
• python-install-mirror 一定要放在 [[index]] 上面，这个顺序错了，解释器下载就不会按预期走。
• TOML 对语法挺敏感，少个引号、写多了逗号都会让配置失效。
• ghfast.top 不可用时，可以换成 ghproxy.com 或其他 GitHub 加速域名，格式保持不变。
• 可以配多个 default = true，但我不建议这么做。它们会落到同一组最低优先级里，行为不够直观，排查起来也麻烦。

最后

UV 的换源其实就两件事：第三方包走 [[index]]，Python 解释器走 python-install-mirror。前者管 PyPI，后者管 astral-sh/python-build-standalone 的下载地址。把这条线分清，配置基本就不会再拧巴了。