国内使用 uv pip install 安装 python 包需配置国内镜像源，可通过临时参数、环境变量、用户级 uv.toml 或项目级 pyproject.toml 四种方式实现，并须验证生效。
在国内使用 uv pip install 安装 Python 包时，常因默认连接国外 PyPI 源导致超时、卡死或下载极慢，必须手动指定国内镜像源才能正常完成安装。
临时指定源（单次命令生效）
方法一：用 -i 参数直接传入镜像地址
在终端中执行：uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ requests
这一步操作起来很简单，直接加参数就行，适合快速验证或偶尔安装单个包。
方法二：用环境变量临时覆盖（当前终端会话有效）
Linux/macOS 执行：UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/" uv pip install numpy
Windows PowerShell 执行：$env:UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"; uv pip install numpy
注意：该方式比 -i 更底层，会同时影响 uv 内部的索引解析逻辑，但只在当前终端窗口内有效。
永久配置用户级镜像源（推荐长期使用）
第一步：确认 uv 配置目录路径
Linux/macOS 路径为 ~/.config/uv/uv.toml；Windows 路径为 %APPDATA%\uv\uv.toml。若目录不存在，需手动创建。
第二步：新建或编辑 uv.toml 文件，写入以下内容：[index]<br>url = "https://pypi.tuna.tsinghua.edu.cn/simple/"<br>default = true
这一步不能漏掉 【default = true】，否则 uv 会忽略该配置，继续走默认国外源。
构建并发布在 Quartz 平台上的韩语网络小说连载（草稿→封面→webp→章节 md→lint→发布），使用 Nano Banana Pro + ffmpeg。
第三步：保存文件后，在任意终端运行 uv config get index.url 验证是否生效。
如果输出为 https://pypi.tuna.tsinghua.edu.cn/simple/，说明配置已加载成功。
项目级配置（仅对当前 pyproject.toml 所在目录生效）
在项目根目录的 pyproject.toml 中添加如下段落：[[tool.uv.index]]<br>url = "https://mirrors.aliyun.com/pypi/simple/"<br>default = true
uv 会优先读取该项目下的配置，覆盖用户级设置。适合多团队协作、需要统一源策略的工程。
注意：此配置仅在执行 uv sync 或 uv pip install 且当前工作目录含该文件时才起作用。
验证镜像源是否真正生效
执行带详细日志的安装命令：uv pip install --dry-run -v flask 2>&1 | grep -i tuna（Linux/macOS）
Windows PowerShell 用户运行：uv pip install --dry-run -v flask 2>&1 | Select-String "tuna"
若输出中出现 GET https://pypi.tuna.tsinghua.edu.cn/simple/flask/，说明请求已实际发往清华源。
这一步不可跳过——很多用户误以为配置完就一定生效，其实 uv 不会报错提示源配置失败，静默回退到默认源是常见行为。
