快速设置uv默认源为国内镜像

对于一些网络“不好”的同学，使用uv下载三方库可能会遇到超时，连接不上的情况，这时候就可以配置国内镜像，直连就可以正常下载。

一、项目内配置

1. 项目目录结构

uv-doc-zh/
├── README.md
├── docs
├── index.py
├── mkdocs.yml
├── pyproject.toml
└── uv.lock

2. 快速配置（推荐）

在 pyproject.toml 中添加以下内容：

[project]
name = "uv-doc-zh"
version = "0.1.0"
description = "一个用 Rust 编写的极其快速的 Python 包和项目管理器。"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "mkdocs-material>=9.6.15",
]

# 腾讯云源
[[tool.uv.index]]
name = "tencent"
url = "https://mirrors.cloud.tencent.com/pypi/simple/"
# url = "https://mirrors.tencentyun.com/pypi/simple/"  # 内网

# 阿里云源
[[tool.uv.index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"
# url = "http://mirrors.cloud.aliyuncs.com/pypi/simple/"  # 内网

# 火山引擎源
[[tool.uv.index]]
name = "volces"
url = "https://mirrors.volces.com/pypi/simple/"
# url = "https://mirrors.ivolces.com/pypi/simple/"  # 内网

# 华为云源
[[tool.uv.index]]
name = "huaweicloud"
url = "https://mirrors.huaweicloud.com/repository/pypi/simple/"

# 清华大学源
[[tool.uv.index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

# 中国科学技术大学源
[[tool.uv.index]]
name = "ustc"
url = "https://pypi.mirrors.ustc.edu.cn/simple/"

3. 配置参数说明

3.1 使用 [[tool.uv.index]]（推荐）

单个镜像源：

[project]
name = "uv-doc-zh"
version = "0.1.0"
description = "一个用 Rust 编写的极其快速的 Python 包和项目管理器。"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "mkdocs-material>=9.6.15",
]

[[tool.uv.index]]
name = "名称"
url = "<镜像源地址>"

多个镜像源：

[[tool.uv.index]]
name = "名称1"
url = "<镜像源地址 1>"

[[tool.uv.index]]
name = "名称2"
url = "<镜像源地址 2>"

3.2 使用 index-url（已弃用）

⚠️ 注意：该方式已弃用，但版本 0.7.20 仍可用。

[project]
name = "uv-doc-zh"
version = "0.1.0"
description = "一个用 Rust 编写的极其快速的 Python 包和项目管理器。"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "mkdocs-material>=9.6.15",
]

[tool.uv]
index-url = "<替换为你需要的镜像源地址>"

4. 国内镜像源列表

二、全局永久配置

方案：永久全局配置（推荐）

步骤 1：打开 uv 配置文件目录

1. 1. 按下 Win + R 打开「运行」窗口
2. 2. 输入 %APPDATA%\uv，回车
3. 3. 如果提示「找不到该文件夹」，手动创建：

   💡 提示：AppData 文件夹默认隐藏，可直接粘贴路径访问

• • 路径：C:\Users\你的用户名\AppData\Roaming\uv

步骤 2：创建/编辑 uv.toml 配置文件

1. 1. 在 uv 文件夹内，右键 → 新建 → 文本文档，重命名为 uv.toml

   ⚠️ 注意：后缀是 .toml，不是 .txt

   💡 需要先显示文件扩展名：文件资源管理器 → 查看 → 勾选「文件扩展名」

2. 2. 双击打开 uv.toml，粘贴以下内容（以清华源为例，最稳定）：

# uv 国内源配置（Windows 全局生效）

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true  # 设置为默认源

# 可选：保留官方源作为备用（无需可删除）
[[index]]
url = "https://pypi.org/simple"

步骤 3：验证镜像源是否生效

# 安装测试包（观察下载速度）
uv pip install numpy

✅ 如果输出中包含 Looking index-url https://pypi.tuna.tsinghua.edu.cn/simple，说明配置成功。

步骤 4：清除缓存（可选）

uv clean

往期相关推荐