OneTree/ShopTRAINING

Fork 0

gdtiti 71a6975159 临时版本

2025-07-02 11:05:23 +08:00

8.5 KiB

Raw Blame History

UV 配置指南 - 缓存与镜像源设置

本文档提供 UV Python 包管理器的本地缓存和国内镜像源配置方法，适用于药店销售预测系统项目。

📋 目录

环境信息
缓存配置
镜像源配置
完整配置示例
实用命令
项目推荐配置
故障排除

🖥️ 环境信息

操作系统: Windows
项目路径: H:\_Workings\_OneTree\_ShopTRAINING
UV版本: 最新版本
Python环境: UV 自动管理

🔧 缓存配置

1. 查看当前缓存配置

# 查看uv缓存目录
uv cache dir

# 查看缓存使用情况
uv cache info

# 查看所有配置
uv config list

2. 设置本地缓存目录

# 方法1：全局配置
uv config set cache-dir "H:\_Workings\uv_cache"

# 方法2：环境变量（PowerShell）
$env:UV_CACHE_DIR = "H:\_Workings\uv_cache"

# 方法3：环境变量（CMD）
set UV_CACHE_DIR=H:\_Workings\uv_cache

3. 项目级缓存配置

在项目根目录的 pyproject.toml 中添加：

[tool.uv]
# 缓存目录
cache-dir = "H:\_Workings\uv_cache"
# 启用缓存
no-cache = false
# 缓存策略：prefer-cache, no-cache, cache-only
cache-policy = "prefer-cache"

🌐 镜像源配置

1. 常用国内镜像源

镜像源	URL	特点
清华大学	`https://pypi.tuna.tsinghua.edu.cn/simple`	稳定，更新及时
阿里云	`https://mirrors.aliyun.com/pypi/simple/`	速度快，商业支持
中科大	`https://pypi.mirrors.ustc.edu.cn/simple/`	学术网络友好
华为云	`https://mirrors.huaweicloud.com/repository/pypi/simple/`	企业级稳定

2. 全局配置镜像源

# 推荐：清华镜像源
uv config set global.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"

# 或者：阿里云镜像源
uv config set global.index-url "https://mirrors.aliyun.com/pypi/simple/"

# 或者：中科大镜像源
uv config set global.index-url "https://pypi.mirrors.ustc.edu.cn/simple/"

3. 环境变量配置

# PowerShell
$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"

# CMD
set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# 批处理文件中使用
@echo off
set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
uv sync

4. 临时使用镜像源

# 单次安装使用镜像源
uv add numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 同步时使用镜像源
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 添加多个镜像源
uv add pytorch --index-url https://pypi.tuna.tsinghua.edu.cn/simple \
              --extra-index-url https://mirrors.aliyun.com/pypi/simple/

📦 完整配置示例

方案1：使用 `uv.toml` 配置文件

在项目根目录创建 uv.toml：

[cache]
# 缓存目录
dir = "H:\_Workings\uv_cache"
# 启用缓存
enabled = true
# 缓存策略
policy = "prefer-cache"

[index]
# 主镜像源
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# 额外镜像源
extra-urls = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://pypi.mirrors.ustc.edu.cn/simple/"
]

[global]
# 信任主机
trusted-hosts = [
    "pypi.tuna.tsinghua.edu.cn",
    "mirrors.aliyun.com",
    "pypi.mirrors.ustc.edu.cn"
]

# 网络配置
timeout = 120
retries = 3

方案2：在 `pyproject.toml` 中配置

[tool.uv]
# 镜像源配置
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://pypi.mirrors.ustc.edu.cn/simple/"
]

# 缓存配置
cache-dir = "H:\_Workings\uv_cache"
no-cache = false

# 信任主机
trusted-host = [
    "pypi.tuna.tsinghua.edu.cn",
    "mirrors.aliyun.com", 
    "pypi.mirrors.ustc.edu.cn"
]

# 网络配置
timeout = 120
retries = 3

# 依赖解析配置
resolution = "highest"
prerelease = "disallow"

🚀 实用命令

缓存管理

# 查看缓存信息
uv cache info

# 清理所有缓存
uv cache clean

# 清理指定包的缓存
uv cache clean numpy pytorch

# 强制重新下载（忽略缓存）
uv sync --refresh

# 仅使用缓存（离线模式）
uv sync --offline

# 预热缓存（提前下载依赖）
uv sync --no-install-project

镜像源测试

# 测试镜像源连通性
uv add --dry-run numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 详细输出查看实际使用的源
uv add numpy --verbose

# 检查包的可用版本
uv tree numpy

# 搜索包
uv search pytorch --index-url https://pypi.tuna.tsinghua.edu.cn/simple

配置管理

# 查看当前配置
uv config list

# 查看特定配置项
uv config get cache-dir

# 删除配置项
uv config unset cache-dir

# 重置所有配置
uv config reset

🎯 项目推荐配置

基于药店销售预测系统的特点，推荐以下配置：

1. 创建项目配置文件

在 H:\_Workings\_OneTree\_ShopTRAINING\pyproject.toml 中添加：

[project]
name = "pharmacy-sales-prediction"
version = "1.0.0"
description = "多店铺药店销售预测系统"
requires-python = ">=3.8"

[tool.uv]
# 镜像源配置（推荐清华源，国内最稳定）
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://mirrors.huaweicloud.com/repository/pypi/simple/"
]

# 缓存配置
cache-dir = "H:\_Workings\_OneTree\_ShopTRAINING\.uv_cache"
no-cache = false

# 信任主机
trusted-host = [
    "pypi.tuna.tsinghua.edu.cn",
    "mirrors.aliyun.com",
    "mirrors.huaweicloud.com"
]

# 网络配置
timeout = 120
retries = 3

# 依赖解析
resolution = "highest"
prerelease = "disallow"

# UV工作目录
dev-dependencies = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=4.0.0"
]

2. 创建批处理启动脚本

创建 配置UV环境.bat：

@echo off
echo 🔧 配置UV环境和镜像源...

:: 设置缓存目录
uv config set cache-dir "H:\_Workings\_OneTree\_ShopTRAINING\.uv_cache"

:: 设置镜像源
uv config set global.index-url "https://pypi.tuna.tsinghua.edu.cn/simple"

:: 设置环境变量
set PYTHONIOENCODING=utf-8
set UV_CACHE_DIR=H:\_Workings\_OneTree\_ShopTRAINING\.uv_cache

echo ✅ UV环境配置完成
echo 📋 当前配置:
uv config list

echo.
echo 🚀 同步项目依赖...
uv sync

echo.
echo 🎉 环境配置和依赖同步完成！
pause

3. 初始化配置

# 进入项目目录
cd "H:\_Workings\_OneTree\_ShopTRAINING"

# 运行配置脚本
.\配置UV环境.bat

# 或手动执行
uv sync --refresh

🔍 故障排除

常见问题及解决方案

1. 网络连接问题

# 问题：连接超时
# 解决：增加超时时间和重试次数
uv config set global.timeout 180
uv config set global.retries 5

# 或使用代理
uv add numpy --proxy http://proxy.company.com:8080

2. SSL证书问题

# 问题：SSL证书验证失败
# 解决：添加信任主机
uv config set global.trusted-host "pypi.tuna.tsinghua.edu.cn"

# 或临时跳过SSL验证（不推荐）
uv add numpy --trusted-host pypi.tuna.tsinghua.edu.cn

3. 缓存问题

# 问题：缓存损坏
# 解决：清理缓存
uv cache clean

# 强制重新下载
uv sync --refresh --no-cache

4. 权限问题

# 问题：缓存目录权限不足
# 解决：更改缓存目录到用户目录
uv config set cache-dir "%USERPROFILE%\.uv_cache"

性能优化建议

使用本地缓存：设置合适的缓存目录，避免重复下载
选择合适的镜像源：根据网络环境选择最快的镜像源
配置多个镜像源：设置备用镜像源，提高可用性
定期清理缓存：避免缓存目录过大影响性能

验证配置

# 验证缓存配置
uv cache info

# 验证镜像源配置
uv config get global.index-url

# 测试安装速度
time uv add --dry-run numpy

# 检查依赖解析
uv tree

📝 总结

通过以上配置，你的UV环境将具备：

✅ 本地缓存：减少重复下载，提升安装速度
✅ 国内镜像源：解决网络访问问题，提高稳定性
✅ 多源备份：确保依赖获取的可靠性
✅ 项目隔离：针对特定项目的定制化配置
✅ 自动化脚本：简化环境配置流程

建议将此配置作为项目的标准环境配置，并在团队中推广使用。

更新日期: 2025-06-23
适用项目: 药店销售预测系统
维护人员: Claude Code

8.5 KiB Raw Blame History Unescape Escape