ShopTRAINING/docs/UV_配置指南.md

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

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

## 📋 目录

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

## 🖥️ 环境信息

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

## 🔧 缓存配置

### 1. 查看当前缓存配置

```bash
# 查看uv缓存目录
uv cache dir

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

# 查看所有配置
uv config list
```

### 2. 设置本地缓存目录

```bash
# 方法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` 中添加：

```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. 全局配置镜像源

```bash
# 推荐：清华镜像源
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. 环境变量配置

```bash
# 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. 临时使用镜像源

```bash
# 单次安装使用镜像源
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`：

```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` 中配置

```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"
```

## 🚀 实用命令

### 缓存管理

```bash
# 查看缓存信息
uv cache info

# 清理所有缓存
uv cache clean

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

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

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

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

### 镜像源测试

```bash
# 测试镜像源连通性
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
```

### 配置管理

```bash
# 查看当前配置
uv config list

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

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

# 重置所有配置
uv config reset
```

## 🎯 项目推荐配置

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

### 1. 创建项目配置文件

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

```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`：

```batch
@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. 初始化配置

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

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

# 或手动执行
uv sync --refresh
```

## 🔍 故障排除

### 常见问题及解决方案

#### 1. 网络连接问题

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

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

#### 2. SSL证书问题

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

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

#### 3. 缓存问题

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

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

#### 4. 权限问题

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

### 性能优化建议

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

### 验证配置

```bash
# 验证缓存配置
uv cache info

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

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

# 检查依赖解析
uv tree
```

## 📝 总结

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

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

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

---

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