ai-shell/配置修复总结.md

配置修复总结

🐛 问题描述

每次运行 uv sync 时，都会在项目目录中创建一个名为 ~ 的文件夹。

🔍 问题原因

在 uv.toml 配置文件中，cache-dir = "~/.cache/uv" 的 ~ 符号没有被正确展开，uv 将其当作字面量处理，导致在当前目录创建了名为 ~ 的文件夹。

✅ 解决方案

1. 修复项目配置文件

修改前 (uv.toml)：

# 缓存目录
cache-dir = "~/.cache/uv"

修改后 (uv.toml)：

# 缓存目录（移除此配置，使用 uv 默认缓存位置）
# cache-dir = "~/.cache/uv"

2. 清理重复配置

问题：pyproject.toml 和 uv.toml 中有重复的 uv 配置，导致警告信息。

解决：删除 pyproject.toml 中的 [tool.uv] 配置段，只保留 uv.toml 中的配置。

修改前 (pyproject.toml)：

[tool.uv]
# 使用国内镜像源加速下载
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://mirrors.cloud.tencent.com/pypi/simple/",
]
index-strategy = "unsafe-best-match"
concurrent-downloads = 10
cache-dir = "~/.cache/uv"

修改后 (pyproject.toml)：

# UV 配置已移至 uv.toml 文件

3. 完善全局配置

创建正确的全局 uv 配置文件 ~/.config/uv/uv.toml：

# UV 全局配置文件
# 配置国内镜像源加速下载

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

# 性能优化配置
index-strategy = "unsafe-best-match"
concurrent-downloads = 10

# 注意：不要设置 cache-dir，让 uv 使用默认位置

🧹 清理操作

1. 删除错误创建的目录：

   rm -rf ./~
   

2. 验证修复效果：

   uv sync
   ls -la | grep "~"  # 应该没有输出
   

📋 最佳实践

1. uv 缓存配置

• ✅ 推荐：不设置 cache-dir，让 uv 使用默认位置
• ❌ 避免：使用 ~ 符号，因为可能不被正确展开
• ✅ 替代：如果必须自定义，使用绝对路径

2. 配置文件优先级

• uv.toml > pyproject.toml 中的 [tool.uv]
• 避免在两个文件中重复配置相同选项

3. 全局 vs 项目配置

• 全局配置 (~/.config/uv/uv.toml)：适用于所有项目的通用设置
• 项目配置 (项目目录/uv.toml)：特定项目的配置，会覆盖全局配置

🔧 当前配置状态

项目配置 (uv.toml)：

# uv 项目配置文件
# 配置国内镜像源加速下载

# 主要的 PyPI 镜像源
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 额外的镜像源
extra-index-url = [
    "https://mirrors.aliyun.com/pypi/simple/",
    "https://mirrors.cloud.tencent.com/pypi/simple/",
]

# 索引策略 - 允许从所有索引中选择最佳版本
index-strategy = "unsafe-best-match"

# 缓存目录（移除此配置，使用 uv 默认缓存位置）
# cache-dir = "~/.cache/uv"

# 并发下载数
concurrent-downloads = 10

全局配置 (~/.config/uv/uv.toml)：

# UV 全局配置文件
# 配置国内镜像源加速下载

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

# 性能优化配置
index-strategy = "unsafe-best-match"
concurrent-downloads = 10

# 注意：不要设置 cache-dir，让 uv 使用默认位置

✅ 验证结果

修复后运行 uv sync：

• ✅ 不再创建 ~ 目录
• ✅ 没有重复配置警告
• ✅ 国内镜像源正常工作
• ✅ 依赖同步正常

---

💡 总结：问题已完全解决，uv 配置现在更加清晰和规范。