修改 uv 缓存目录路径，需要在环境变量中设置 uv_cache_dir。将该变量指向目标文件夹后，uv 会自动将包和元数据写入该位置，从而释放默认路径（通常是用户主目录下的隐藏文件夹）占用的磁盘空间。
如何配置环境变量生效
在 Linux 或 macOS 系统中，可以通过编辑 shell 配置文件来永久设置该变量。打开终端并编辑 .bashrc 或 .zshrc 文件，添加一行 export UV_CACHE_DIR=/path/to/new/cache。保存后运行 source ~/.bashrc 使配置立即生效。Windows 用户则可以在系统属性的高级设置中添加名为 UV_CACHE_DIR 的用户或系统环境变量。
export UV_CACHE_DIR=/mnt/data/uv_cache # 验证配置是否生效 env | grep UV_CACHE_DIR
执行上述命令后，终端应输出你设置的目标路径。此时再运行 uv sync 或 uv pip install，生成的缓存文件就会出现在新指定的目录中。如果未设置该变量，uv 会回退到默认行为，即使用 $HOME/.local/share/uv (Linux/macOS) 或 %LOCALAPPDATA%\uv (Windows) 作为缓存根目录。
立即学习“Python免费学习笔记（深入）”；
不同操作系统下的具体路径差异
了解默认路径有助于判断何时需要修改。在类 Unix 系统上，默认路径位于 $HOME/.local/share/uv，这通常与 pip 的缓存位置 $HOME/.cache/pip 类似。而在 Windows 上，它位于应用数据目录 %LOCALAPPDATA%\uv。如果你的系统盘空间紧张，或者希望将缓存集中管理以便定期清理，修改此路径是非常有效的做法。
# Linux/macOS 默认路径结构 $HOME/.local/share/uv/ ├── packages/ └── metadata.json # Windows 默认路径结构 C:\Users\<User>\AppData\Local\uv\ ├── packages\ └── metadata.json
通过对比可以发现，无论哪个平台，uv 都遵循各自操作系统的标准数据存储规范。修改路径时，请确保目标目录存在且具有读写权限。如果目标目录不存在，uv 可能会报错或无法正确创建缓存结构。建议在设置环境变量前，先手动创建好目标文件夹，例如使用 mkdir -p /new/cache/path，以避免潜在的权限问题。
基于 UV_CACHE_DIR 设置后的实际存储结构变化
当 UV_CACHE_DIR 被成功设置后，uv 会在该目录下创建一个与默认结构一致的子目录树。具体来说，它会生成 packages 目录用于存放下载的 wheel 文件，以及 metadata.json 用于记录包的版本和依赖关系。这种结构的一致性意味着你可以使用相同的工具或脚本来管理和清理缓存，无需关心具体的路径位置。
在实际使用中，如果你发现缓存占用过大，可以直接删除 UV_CACHE_DIR 下的内容，uv 会在下次需要时重新下载必要的包。这种灵活性使得自定义缓存路径成为优化开发环境磁盘使用的关键手段。确保在 CI/CD 管道或团队协作中，所有成员都使用一致的环境变量配置，可以避免因缓存路径不一致导致的构建差异。
