国内用uv安装Python库卡顿的根本原因是默认连接海外PyPI源；需配置清华镜像源（如UV_DEFAULT_INDEX环境变量或uv.toml），再通过uv pip install或uv add安装，最后用uv pip index list和--dry-run验证生效。
在国内网络环境下用uv安装Python第三方库经常卡住或超时，根本原因是默认连接海外PyPI源；不配镜像源，uv再快也跑不起来。
用uv安装第三方库
这一步操作起来很简单，直接在项目根目录终端里运行命令即可：
uv pip install requests
注意：uv pip install 和 uv add 是两个不同语义的命令——前者直接装进当前Python环境（类似传统pip），后者是向pyproject.toml声明依赖并同步安装（推荐用于新项目）。如果你没初始化uv项目，就用uv pip install；如果已有pyproject.toml且想走现代工作流，用uv add requests。
立即学习“Python免费学习笔记（深入）”；
uv add requests会自动创建虚拟环境、解析依赖树、下载并安装，整个过程原子化，失败即回滚，不会留下半残环境。
配置uv国内镜像源（永久生效）
推荐优先使用环境变量方式，一次设置，所有终端、所有项目、所有uv命令都自动生效，不污染项目配置，换电脑重装系统后也只需再设一次。
方法一：Windows图形界面（小白首选）
按Win+R → 输入sysdm.cpl → 回车 → 高级 → 环境变量 → 在“系统变量”区域点击“新建” → 变量名填【UV_DEFAULT_INDEX】 → 变量值填https://pypi.tuna.tsinghua.edu.cn/simple → 连续点确定保存 → 关闭所有已打开的终端窗口，重新打开一个新的CMD或PowerShell。
方法二：macOS/Linux终端命令（一行搞定）
echo 'export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.zshrc && source ~/.zshrc
方法三：全局配置文件（跨shell兼容）
Linux/macOS：执行mkdir -p ~/.config/uv，然后创建~/.config/uv/uv.toml，写入以下内容：
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
Windows用户请在%APPDATA%\uv\uv.toml中写入相同内容。注意路径必须准确，uv不会自动创建父目录，【若uv.toml所在文件夹不存在，配置将完全无效】。
验证镜像源是否生效
第一步：确保终端已重启（关键！旧终端不读新环境变量）。
第二步：运行以下命令查看uv当前使用的源地址：
uv pip index list
第三步：观察输出中default标记是否指向https://pypi.tuna.tsinghua.edu.cn/simple。如果不是，说明配置未加载成功，重点检查环境变量拼写（UV_DEFAULT_INDEX大小写必须完全一致）或uv.toml路径是否正确。
第四步：执行一次真实安装测试：
uv pip install --dry-run flask
如果看到下载链接域名是pypi.tuna.tsinghua.edu.cn，而不是pypi.org，说明镜像源已成功接管流量。
