在 Windows 环境下使用 uv add 安装 Python 依赖时，很多人都会遇到类似下面的警告：
warning: Failed to hardlink files; falling back to full copy.
This may lead to degraded performance.
安装虽然能正常完成，但这个警告让人心里不爽。本文将结合实际案例，解释这个警告到底是什么意思、为什么在 Windows 上很常见，以及一个推荐的、长期有效的解决方案。
一、这个警告是什么意思？
uv 为了获得极高的安装性能，默认会尝试使用 hardlink（硬链接） 的方式：
- 将包文件从
uv的缓存目录 - 硬链接到项目的虚拟环境中
这样做的好处是：
- 几乎不拷贝数据（速度极快）
- 不重复占用磁盘空间
但如果 hardlink 创建失败，uv 会自动退回到 完整复制（copy），并输出这个警告。
需要强调的是：
这是一个性能警告，不是错误。
包已经正确安装，运行时行为完全不受影响。
二、为什么在 Windows 上特别容易出现？
hardlink 在 Windows 上有一个硬性前提：
源文件和目标文件必须位于同一个文件系统（同一个盘符）
而 Windows 用户非常常见的场景是：
-
系统盘：
C: -
项目代码放在：
D:/E: -
uv默认缓存目录却在：C:\Users\<用户名>\AppData\Local\uv\cache
此时：
- cache 在
C: - 项目 / venv 在
D: - hardlink 无法跨盘符创建 ❌
于是 uv 只能退回到 copy，并给出警告。
这正是 GitHub 上 astral-sh/uv#7285 中讨论的问题本质。
三、正确且推荐的解决方案
与其“关闭警告”，不如恢复 uv 的最佳工作方式。
核心思路
把
uv的 cache 目录放到和项目相同的磁盘上
这样 hardlink 就可以正常工作了。
四、永久解决方案（推荐）
1️⃣ 查看当前 cache 位置
uv cache dir
通常你会看到它在 C: 盘。
2️⃣ 在项目所在盘符创建 cache 目录
例如你的项目在 D:：
D:\uv-cache
3️⃣ 永久设置环境变量 UV_CACHE_DIR
PowerShell（推荐）
setx UV_CACHE_DIR D:\uv-cache
说明：
- 永久生效（用户级）
- 重启终端后生效
- 不影响系统稳定性
4️⃣ 打开新终端并验证
uv cache dir
确认输出路径已经变为 D:\uv-cache。
5️⃣ 重新安装依赖
uv add google-genai
此时：
- 不再出现 hardlink 警告
- 安装速度明显更快
- 磁盘占用更低
五、为什么不推荐直接“关闭警告”？
你可能还见过另一种做法：
setx UV_LINK_MODE copy
这确实可以永久消除警告，但代价是：
- 永远不再使用 hardlink
- 每次安装都走慢速 copy
- 丧失
uv的核心性能优势
结论：
UV_LINK_MODE=copy是“绕开问题”UV_CACHE_DIR是“解决问题”
六、总结
| 项目 | 结论 |
|---|---|
| 警告是否影响使用 | ❌ 不影响 |
| 问题根因 | Windows 不支持跨盘 hardlink |
| 最佳解决方案 | 设置 UV_CACHE_DIR 到同盘 |
| 是否推荐永久设置 | ✅ 强烈推荐 |
| 是否需要管理员权限 | ❌ 不需要 |
如果你在 Windows 上频繁使用 uv，并且项目不在 C: 盘，那么设置 UV_CACHE_DIR 几乎是必做项。