高级配置与性能优化

HSXISAWD2026/3/20大约 7 分钟

高级配置与性能优化

深度定制 uv 行为与最大化性能

配置系统概述

uv 支持多层次的配置系统，从全局到项目级别：

配置文件

全局配置 (uv.toml)

创建用户级配置文件：

Linux/macOS: ~/.config/uv/uv.toml
Windows: %APPDATA%\uv\uv.toml

# 包索引配置
index-url = "https://pypi.org/simple"
extra-index-url = [
    "https://pypi.tuna.tsinghua.edu.cn/simple",
]

# 网络设置
connect-timeout = 30
read-timeout = 60

# 并发设置
concurrent-downloads = 50
concurrent-builds = 4
concurrent-installs = 8

# 缓存设置
cache-dir = "~/.cache/uv"
# no-cache = false

# Python 设置
python-preference = "managed"
python-downloads = "automatic"

# 链接模式
link-mode = "symlink"

# 输出设置
# no-progress = false
# quiet = false
# verbose = false

项目配置 (pyproject.toml)

[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "flask>=3.0",
    "requests>=2.28",
]

[tool.uv]
# 开发依赖
dev-dependencies = [
    "pytest>=7.0",
    "ruff>=0.1.0",
]

# Python 版本
python-version = "3.11"

# 索引配置
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
extra-index-url = ["https://pypi.org/simple"]

# 依赖覆盖
override-dependencies = [
    "requests>=2.30,<3.0",
]

# 约束依赖
constraint-dependencies = [
    "numpy<2.0",
]

# 预发布策略
prerelease = "if-necessary"

# 时间戳锁定
exclude-newer = "2024-06-01T00:00:00Z"

# 解析模式
resolution = "highest"

# 虚拟环境路径
venv = ".venv"

环境变量

完整的环境变量列表：

变量	描述	默认值
`UV_INDEX_URL`	主包索引 URL	pypi.org
`UV_EXTRA_INDEX_URL`	额外索引 URL	-
`UV_CACHE_DIR`	缓存目录	平台特定
`UV_NO_CACHE`	禁用缓存	false
`UV_PYTHON`	Python 解释器路径	-
`UV_PYTHON_PREFERENCE`	Python 查找偏好	managed
`UV_PYTHON_DOWNLOADS`	允许下载 Python	automatic
`UV_OFFLINE`	离线模式	false
`UV_NO_PROGRESS`	禁用进度条	false
`UV_QUIET`	静默模式	false
`UV_VERBOSE`	详细输出	false
`UV_NATIVE_TLS`	使用系统 TLS	false
`UV_LINK_MODE`	链接模式	symlink
`UV_CONCURRENT_DOWNLOADS`	并发下载数	50
`UV_CONCURRENT_BUILDS`	并发构建数	4
`UV_HTTP_TIMEOUT`	HTTP 超时（秒）	30
`UV_SYSTEM_PYTHON`	允许使用系统 Python	false
`UV_BREAK_SYSTEM_PACKAGES`	允许破坏系统包	false
`UV_PROJECT_ENVIRONMENT`	项目虚拟环境路径	.venv
`UV_PUBLISH_TOKEN`	PyPI 发布 token	-
`UV_PUBLISH_URL`	发布 URL	-

包索引配置

使用国内镜像

# pyproject.toml
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 或使用环境变量
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

常用镜像源

镜像	URL
清华	https://pypi.tuna.tsinghua.edu.cn/simple
阿里云	https://mirrors.aliyun.com/pypi/simple
腾讯云	https://mirrors.cloud.tencent.com/pypi/simple
华为云	https://repo.huaweicloud.com/repository/pypi/simple
中科大	https://pypi.mirrors.ustc.edu.cn/simple

多索引配置

[tool.uv]
# 主索引
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# 备用索引（按顺序查找）
extra-index-url = [
    "https://pypi.org/simple",
    "https://internal.company.com/simple",
]

# 为特定包指定索引
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

[[tool.uv.index]]
name = "internal"
url = "https://internal.company.com/simple"

[tool.uv.sources]
torch = { index = "pytorch" }
company-lib = { index = "internal" }

私有仓库认证

# 使用 .netrc 文件
# ~/.netrc
machine internal.company.com
login username
password secret_token

# 或环境变量
UV_EXTRA_INDEX_URL="https://user:token@internal.company.com/simple"

缓存管理

缓存结构

# 查看缓存目录
uv cache dir
# ~/.cache/uv (Linux)
# ~/Library/Caches/uv (macOS)
# %LOCALAPPDATA%\uv\cache (Windows)

# 缓存结构
~/.cache/uv/
├── archive-v0/          # 下载的包存档
├── built-wheels-v0/     # 构建的 wheel
├── git-v0/             # Git 仓库克隆
├── interpreter-v0/     # Python 解释器信息
└── wheels-v3/          # wheel 缓存

缓存命令

# 清理所有缓存
uv cache clean

# 清理特定包的缓存
uv cache clean requests

# 移除未使用的缓存条目
uv cache prune

# 查看缓存大小
du -sh $(uv cache dir)

# 查看缓存目录
ls -la $(uv cache dir)

自定义缓存位置

# 环境变量
export UV_CACHE_DIR=/opt/uv-cache

# 命令行参数
uv sync --cache-dir /opt/uv-cache

# 配置文件
[tool.uv]
cache-dir = "/opt/uv-cache"

禁用缓存

# 完全禁用缓存（不推荐，仅用于调试）
UV_NO_CACHE=true uv sync

# 命令行
uv sync --no-cache

性能优化

并发设置

# pyproject.toml 或 uv.toml
[tool.uv]
# 并发下载数（默认 50）
concurrent-downloads = 100

# 并发构建数（默认 CPU 核心数）
concurrent-builds = 8

# 并发安装数（默认 8）
concurrent-installs = 16

链接模式

# 符号链接（默认，最快）
link-mode = "symlink"

# 硬链接（跨文件系统不支持）
link-mode = "hardlink"

# 复制（兼容性最好，最慢）
link-mode = "copy"

网络优化

[tool.uv]
# 连接超时
connect-timeout = 30

# 读取超时
read-timeout = 60

# 使用系统 TLS（可能更快）
native-tls = true

# 使用代理
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080

# 或在命令行
uv sync --proxy http://proxy:8080

CI/CD 优化

# GitHub Actions 示例
- name: Install uv
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"

- name: Install dependencies
  run: |
    uv sync --frozen
  env:
    UV_NO_PROGRESS: true
    UV_CONCURRENT_DOWNLOADS: 100

离线模式

# 预热缓存
uv sync

# 后续离线使用
UV_OFFLINE=true uv sync --frozen

依赖解析配置

解析策略

[tool.uv]
# 使用最高版本（默认）
resolution = "highest"

# 使用最低兼容版本
resolution = "lowest"

# 直接依赖用最低版本，传递依赖用最高版本
resolution = "lowest-direct"

预发布版本

[tool.uv]
# 禁止预发布（默认）
prerelease = "disallow"

# 允许预发布
prerelease = "allow"

# 必要时使用预发布
prerelease = "if-necessary"

# 仅在直接依赖中允许
prerelease = "if-necessary-or-explicit"

时间戳锁定

锁定依赖到特定时间点之前的版本：

[tool.uv]
# 不使用该日期之后发布的版本
exclude-newer = "2024-06-01T00:00:00Z"

这对于：

可重现构建
安全审计
调试版本问题

依赖覆盖

[tool.uv]
# 强制使用特定版本，忽略其他约束
override-dependencies = [
    "requests>=2.30,<3.0",
    "numpy>=1.24,<2.0",
]

# 添加约束，与其他约束合并
constraint-dependencies = [
    "urllib3<2.0",
]

Python 版本配置

版本偏好

[tool.uv]
# 优先使用 uv 管理的 Python（默认）
python-preference = "managed"

# 优先使用系统 Python
python-preference = "system"

# 只使用 uv 管理的 Python
python-preference = "only-managed"

# 只使用系统 Python
python-preference = "only-system"

自动下载

[tool.uv]
# 自动下载需要的 Python（默认）
python-downloads = "automatic"

# 需要时提示用户确认
python-downloads = "manual"

# 从不下载
python-downloads = "never"

固定版本

[tool.uv]
# 项目使用的 Python 版本
python-version = "3.11"

输出与日志

输出控制

# 静默模式
uv sync --quiet

# 详细模式
uv sync --verbose

# 禁用进度条
uv sync --no-progress

# 彩色输出
uv sync --color always
uv sync --color never
uv sync --color auto

日志级别

# 设置日志级别
UV_LOG=debug uv sync
UV_LOG=info uv sync
UV_LOG=warn uv sync
UV_LOG=error uv sync

# 调试网络请求
RUST_LOG=uv_client=debug uv sync

CI 友好输出

# GitHub Actions
- name: Install dependencies
  run: uv sync --frozen
  env:
    UV_NO_PROGRESS: true
    UV_COLOR: never

安全配置

哈希验证

# 使用带哈希的 requirements
uv pip compile requirements.in --generate-hashes -o requirements.txt

# 安装时验证哈希
uv pip sync requirements.txt

可信主机

[tool.uv]
# 信任特定主机（跳过 SSL 验证）
trusted-host = ["internal.company.com"]

网络安全

# 使用系统证书
UV_NATIVE_TLS=true uv sync

# 指定 CA 证书
UV_SSL_CA_BUNDLE=/path/to/ca-bundle.crt uv sync

工作区配置

工作区结构

# 根目录 pyproject.toml
[tool.uv.workspace]
members = [
    "packages/*",
    "apps/*",
]
exclude = [
    "packages/deprecated-*",
]

monorepo/
├── pyproject.toml          # 工作区根配置
├── uv.lock                 # 统一锁文件
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── utils/
│       ├── pyproject.toml
│       └── src/
└── apps/
    └── web/
        ├── pyproject.toml
        └── src/

工作区依赖

# packages/core/pyproject.toml
[project]
name = "myproject-core"
dependencies = []

# apps/web/pyproject.toml
[project]
name = "myproject-web"
dependencies = [
    "myproject-core",  # 引用工作区内的包
]

[tool.uv.sources]
myproject-core = { workspace = true }

调试与故障排查

常用调试命令

# 查看配置来源
uv sync --verbose 2>&1 | grep -i config

# 检查解析过程
UV_LOG=debug uv lock

# 验证锁文件
uv lock --check

# 清理后重试
rm -rf .venv uv.lock
uv sync

网络调试

# 详细的 HTTP 日志
RUST_LOG=uv_client=debug uv sync

# 检查索引访问
curl -I https://pypi.org/simple/requests/

# 测试代理
curl --proxy http://proxy:8080 https://pypi.org

常见问题解决

# SSL 错误
UV_NATIVE_TLS=true uv sync

# 超时错误
UV_HTTP_TIMEOUT=120 uv sync

# 权限错误
chmod +x .venv/bin/python

# 缓存损坏
uv cache clean
uv sync

配置示例

开发环境配置

# pyproject.toml
[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "flask>=3.0",
    "sqlalchemy>=2.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
    "pre-commit>=3.0",
]

python-version = "3.11"

生产环境配置

[tool.uv]
# 使用最高稳定版本
resolution = "highest"
prerelease = "disallow"

# 锁定时间戳
exclude-newer = "2024-06-01T00:00:00Z"

# 使用国内镜像
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

CI 配置

# .github/workflows/ci.yml
env:
  UV_NO_PROGRESS: true
  UV_CACHE_DIR: /tmp/uv-cache
  UV_FROZEN: true

jobs:
  test:
    steps:
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - run: uv sync --frozen
      - run: uv run pytest

总结

关键配置项

类别	配置项	推荐值
索引	`index-url`	使用镜像加速
缓存	`cache-dir`	共享目录
并发	`concurrent-downloads`	50-100
链接	`link-mode`	symlink
Python	`python-preference`	managed
解析	`resolution`	highest

性能优化清单

下一步

企业实践与迁移指南 - 团队使用最佳实践
与其他工具对比分析 - 工具选型参考