🚀 一招搞定！为 uv 配置国内镜像源，让 Python 包下载速度飞起来（全系统通用）
还在为
uv add慢到怀疑人生？还在看着进度条像蜗牛一样蠕动？别慌！今天手把手教你给uv配置国内镜像源，无论你用 Windows、macOS 还是 Linux，都能轻松把下载速度拉满。全是干货，小白也能看懂！
🤔 为什么要配镜像源？
你可以把 PyPI 官方源想象成美国的一家大型仓库，而我们访问它的速度，就像从中国海运包裹——慢、还容易断。国内的镜像源（比如清华、阿里云、腾讯云）就是这些大厂在国内建的“分仓库”，数据每小时同步一次，下载速度直接从“海运”升级到“同城闪送”！
配好镜像源后：
uv add requests从几分钟 -> 几秒钟- 再也不怕超时、连接失败
- 团队协作时环境统一，不踩坑
📦 uv 的镜像源配置逻辑
uv 读取镜像源的顺序是（优先级从高到低）：
- 命令行参数：
uv add --default-index <URL> - 环境变量：
UV_DEFAULT_INDEX或UV_INDEX_URL - 项目配置文件：
pyproject.toml中的[[tool.uv.index]] - 全局配置文件：
uv.toml（用户级或系统级）
我们今天主角是 环境变量，因为它一次配置，全局生效，而且不污染项目配置，换电脑、换用户都方便。
🧪 什么是环境变量？（小白比喻）
环境变量就像操作系统的“便签纸”。你在上面写了
UV_DEFAULT_INDEX=https://...，然后所有程序（包括uv）在运行的时候都会偷偷看一眼这张便签纸，看到后就会自动使用你写的镜像源。
临时设置就像用铅笔在桌面便签纸上写，关了终端就擦掉了。
永久设置就像用马克笔写在系统注册表/配置文件里，关机重启还在。
🪟 Windows 系统配置全攻略
1️⃣ 临时设置（仅当前 CMD 窗口有效）
打开 命令提示符 (CMD)，输入：
set UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
然后运行 uv add 包名，这次会话会使用清华源。关掉窗口就没了。
注意：临时设置只对当前 CMD 窗口生效，如果打开了多个窗口，每个都需要单独设置。
2️⃣ 永久设置（推荐，一劳永逸）
方法一：图形界面（最适合小白）
- 按
Win + R，输入sysdm.cpl，回车。 - 点击 高级 → 环境变量。
- 在 用户变量 或 系统变量 区域，点击 新建：
- 变量名：
UV_DEFAULT_INDEX - 变量值：
https://pypi.tuna.tsinghua.edu.cn/simple
- 变量名：
- 一路点 确定，然后重启你的终端。
✅ 搞定！以后每个新 CMD 窗口都会自动使用这个镜像源。
方法二：命令行永久设置（适合极客）
以管理员身份打开 CMD，然后：
:: 为当前用户永久设置
setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple"
:: 或者为所有用户永久设置（需要管理员权限）
setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple" /M
💡 小提示：
setx写入的是注册表，不会影响当前已打开的 CMD 窗口。你需要新开一个 CMD 才能看到效果。
🍎 macOS / 🐧 Linux 系统配置全攻略
这两兄弟都是 Unix 系，配置方法几乎一样。
1️⃣ 临时设置（仅当前终端会话有效）
打开 终端 (Terminal)，输入：
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
然后运行 uv add 包名。关掉这个终端标签页，配置就消失了。
2️⃣ 永久设置（推荐）
你需要把 export 命令写进 shell 的配置文件里。不同的 shell 对应的文件不同：
| Shell 类型 | 配置文件路径 |
|---|---|
| Bash (最常见) | ~/.bashrc 或 ~/.bash_profile |
| Zsh (macOS 默认) | ~/.zshrc |
| Fish | ~/.config/fish/config.fish |
操作步骤（以 Zsh 为例，macOS 默认）：
- 打开终端，用文本编辑器打开配置文件：
nano ~/.zshrc - 在文件末尾另起一行，添加：
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple" - 保存并退出（nano 中是
Ctrl+O，回车，再Ctrl+X）。 - 让配置立即生效：
source ~/.zshrc
✅ 以后每次打开新终端，镜像源都会自动设置。
如果你用的是 Bash（比如 Ubuntu 默认），就把
~/.zshrc换成~/.bashrc。
🔄 如何验证配置是否生效？
配置好后，别着急用，先验证一下，免得白忙活。
验证环境变量是否写入成功
- Windows CMD：
echo %UV_DEFAULT_INDEX% - macOS/Linux：
echo $UV_DEFAULT_INDEX
应该输出你设置的镜像源地址，比如 https://pypi.tuna.tsinghua.edu.cn/simple。
验证 uv 是否真的在用镜像源
运行一个测试安装：
uv add --dry-run requests # 只查看将要下载的源，不实际安装
或者直接安装并观察输出：
uv add requests
如果日志里出现 Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple，并且下载速度起飞，就说明成功了！
🗺️ 国内常用镜像源地址（直接复制）
| 镜像站 | URL |
|---|---|
| 🌟 清华大学 | https://pypi.tuna.tsinghua.edu.cn/simple |
| ☁️ 阿里云 | https://mirrors.aliyun.com/pypi/simple |
| 🐧 腾讯云 | https://mirrors.cloud.tencent.com/pypi/simple |
| 📡 华为云 | https://repo.huaweicloud.com/repository/pypi/simple |
| 🎬 豆瓣 | https://pypi.doubanio.com/simple |
建议：优先使用清华或阿里云，速度快且稳定。如果某个源突然变慢，切换另一个试试。
🧠 常见问题 FAQ
❓ 我设置了环境变量，为什么 uv 还是从官方源下载？
- 检查环境变量名是否写错。必须是
UV_DEFAULT_INDEX全大写，下划线不能少。 - 可能项目里的
pyproject.toml或uv.toml显式指定了其他源，且优先级更高。可以运行uv config list -v查看所有配置的来源。 - Windows 上用
setx后，需要新开 CMD 窗口，当前窗口不生效。
❓ 临时设置和永久设置哪个好？
- 临时：适合测试不同镜像源，或者偶尔翻墙需要切换。
- 永久：适合日常开发，一劳永逸。
❓ 我只想给某个项目单独配置镜像源，怎么办？
在项目根目录的 pyproject.toml 里加入：
[tool.uv]
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
这样只会影响这个项目，不会污染全局。
❓ 环境变量和 uv.toml 配置文件哪个优先级高？
环境变量 > 命令行参数 > 项目配置文件 > 全局配置文件。
也就是说，如果你同时设置了环境变量和 uv.toml，环境变量会胜出。
🎉 总结
| 操作系统 | 临时设置命令 | 永久设置方法 |
|---|---|---|
| Windows CMD | set UV_DEFAULT_INDEX=... | GUI 环境变量 / setx UV_DEFAULT_INDEX "..." |
| macOS / Linux (bash/zsh) | export UV_DEFAULT_INDEX="..." | 写入 ~/.bashrc 或 ~/.zshrc |
配置完镜像源后，uv add 就像坐上了火箭，再也不用盯着进度条发呆了。赶紧动手试试吧！
如果你觉得这篇文章帮到了你，欢迎点赞、收藏、转发，让更多被慢速折磨的小伙伴看到～ 🚀
本文内容基于 uv 0.5+ 版本，命令若有变动请参考官方文档。如有疑问，欢迎评论区讨论。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/qq_51553749/article/details/161788765
