420 lines
8.5 KiB
Markdown
420 lines
8.5 KiB
Markdown
# 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 |