uv 0.1.x 版本史精读：pip 接口、缓存、认证与持久化配置的完整演进-育师

uv 0.1.x 版本史精读：pip 接口、缓存、认证与持久化配置的完整演进

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

uv 0.1.x 系列是该项目从"pip 替代工具"走向"完整 Python 项目管理器"的关键阶段，覆盖 0.1.1 到 0.1.45 共 45 个补丁版本，其发布记录完整保留在 changelogs/0.1.x.md 中。本篇基于该变更日志逐段展开，结合当前仓库的源码布局与文档，梳理这一时期uv pip各子命令的补齐过程、环境变量与持久化配置的引入节奏、认证与缓存体系的关键修复，以及 0.1.40 起以预览功能形式登场的项目接口——这些预览功能正是后来uv sync、uv.lock项目工作流的直接前身。

0.1.x 系列的整体脉络

从变更日志的章节分布可以归纳出 0.1.x 期的四条主线：

pip 接口能力补齐（compile、sync、install先行，list、show、check、freeze随后逐个落地）；
配置面扩张（环境变量从个别开关扩展到覆盖索引、超时、认证、链接模式等，0.1.42 起引入持久化配置文件）；
认证与 TLS 体系修正（.netrc、keyring、系统信任存储、--native-tls开关）；
缓存与解析性能优化（预取、并行解析器、内存索引）。

当前仓库中 0.1.x 期引入的命令与今日实现一脉相承，可以在 crates/uv/src/commands/pip/ 目录下看到compile.rs、sync.rs、install.rs、list.rs、show.rs、check.rs、freeze.rs、uninstall.rs等命令实现文件，它们对应的正是日志中各版本"新增某命令"的记录。

pip 子命令的逐步补齐

早期：install 与 compile 的升级能力（0.1.1–0.1.2）

0.1.1 修复了python3不在全局路径时的查找问题；0.1.2 是 pip 接口的重要一步：

pip install支持--upgrade，并新增-U/-P短标志（--upgrade/--upgrade-package）；
新增UV_NO_CACHE环境变量，uv-cache增加--no-cache-dir隐藏别名；
一系列requirements.txt解析修正：-r/-c条目相对包含文件解析、尾逗号处理、HTML 索引中相对 URL 解析等。

中前期：内省命令落地（0.1.6–0.1.22）

按日志顺序，环境内省类命令的引入节奏为：

版本	命令/能力	说明
0.1.6	`uv cache dir`	显示缓存目录；`uv clean`同时更名为`uv cache clean`，缓存操作统一收归`uv cache`子命令树
0.1.6	`venv --prompt`、创建后打印激活指令	改进 venv 体验，`-f`成为`--find-links`别名，并新增 shell 补全生成
0.1.11	`uv pip list`、`freeze`round-trip	支持`--exclude-editable`/`--exclude`（0.1.12 补充），`freeze`输出可再次作为输入
0.1.16	`uv pip show`	0.1.18 补充 "Requires" 字段，0.1.25 再补充`Editable project location`与`Required-by`
0.1.22	`uv pip check`	环境一致性检查
0.1.23	`uv self update`	自更新命令，0.1.24 起改为 opt-in 的 Cargo feature，0.1.28 修复 Linux 上的自更新

0.1.6 引入的uv cache dir在当前仓库中的实现是 cache_dir.rs，逻辑非常直接：取出Cache根路径并以简化形式打印。缓存清理相关的 cache_clean.rs、cache_prune.rs 等也属于这一子命令树的组成部分；0.1.24 引入的缓存垃圾回收机制（uv cache prune）即在此后持续演进。

解释器选择的两次关键增强（0.1.12、0.1.14–0.1.16）

0.1.12 引入的两个全局开关影响深远：

--python：允许将包装入任意 Python 解释器；
--system：显式选择非虚拟环境的系统解释器，同时开始向用户透出EXTERNALLY-MANAGED错误信息。

随后的修复大量围绕 Windows 解释器发现展开（Windows Store shim、pylauncher 的 stderr 干扰、pyenv shim 等），0.1.14 起uv venv支持--system-site-packages。0.1.16 进一步补充--no-build-isolation与--break-system-packages，并让--system安装兼容 Debian 等非 sysconfig 体系发行版——从变更日志看，这正是 uv 从"仅支持干净虚拟环境"走向"尊重各类系统 Python"的转折。

环境变量与持久化配置的演进

环境变量时间线

0.1.x 期引入的环境变量在日志中有明确记录，按主题归类：

缓存：UV_NO_CACHE（0.1.2）；
索引：UV_EXTRA_INDEX_URL（0.1.3 引入，0.1.14 改用空格分隔），UV_INDEX_URL等由索引参数派生；
超时：UV_HTTP_TIMEOUT与通用HTTP_TIMEOUT（0.1.7），0.1.35 将超时语义改为按读取计时而非按请求计时，0.1.37 把默认 HTTP 读取超时调整为 30 秒；
TLS/认证：UV_NATIVE_TLS（0.1.19）、UV_KEYRING_PROVIDER系列；
解析行为：UV_PRERELEASE（0.1.16）、UV_RESOLUTION（0.1.27）、UV_CONSTRAINT（0.1.36）；
安装目标：UV_SYSTEM_PYTHON（0.1.18 作为--system别名）、UV_BREAK_SYSTEM_PACKAGES（0.1.32）、UV_PYTHON（0.1.40）、UV_LINK_MODE（0.1.40）、UV_NO_BUILD_ISOLATION（0.1.40）；
安全：UV_REQUIRE_HASHES（0.1.34）；
并发：UV_CONCURRENT_INSTALLS（0.1.45 取代RAYON_NUM_THREADS的作用）。

这些环境变量在今天的源码中依然以 clap 参数形式绑定，可以在 crates/uv-cli/src/lib.rs 中检索到env = EnvVars::UV_PYTHON、env = EnvVars::UV_SYSTEM_PYTHON、env = EnvVars::UV_BREAK_SYSTEM_PACKAGES、env = EnvVars::UV_LINK_MODE、env = EnvVars::UV_CONSTRAINT、env = EnvVars::UV_RESOLUTION、env = EnvVars::UV_REQUIRE_HASHES、env = EnvVars::UV_EXTRA_INDEX_URL、env = EnvVars::UV_CONFIG_FILE等声明，说明 0.1.x 期建立的"每个 CLI 开关都有环境变量对应"的惯例被延续至今。0.1.34 还统一了布尔环境变量的取值，接受0/1这类值；0.1.35 允许UV_SYSTEM_PYTHON=1。

0.1.42：持久化配置的稳定化

0.1.42 是配置面最重要的版本，日志原文说明：

uv will now read project configuration from apyproject.tomloruv.tomlfile in the current directory or any parent directory, along with user configuration at~/.config/uv/uv.toml(or$XDG_CONFIG_HOME/uv/uv.toml) on macOS and Linux, and%APPDATA%\uv\uv.tomlon Windows.

即：项目级配置从当前目录及父目录的pyproject.toml（读取[tool.uv]表）或uv.toml读取，用户级配置位于~/.config/uv/uv.toml（macOS/Linux）或%APPDATA%\uv\uv.toml（Windows）。同版本还把 JSON Schema 导出到了 SchemaStore（仓库中的 uv.schema.json 即其产物），并合并了用户与工作区设置。

这一机制在当前文档 docs/concepts/configuration-files.md 中有完整说明，包括后续新增的系统级配置（/etc/uv/uv.toml）以及uv.toml优先于pyproject.toml的规则。配置合并逻辑也在 0.1.45 进一步完善："Apply combination logic to merge CLI and persistent configuration"（#3618）。

认证与网络栈的加固

0.1.x 的认证演进脉络非常清晰：

0.1.3：HTTPS 请求改用系统信任存储；
0.1.16：支持.netrc认证（配套 crate 为 crates/uv-netrc/），同期支持远程https://requirements 文件；
0.1.18（破坏性变更）：依赖原生根证书或SSL_CERT_FILE的用户必须显式传--native-tls，实现运行时 TLS 切换；0.1.19 随即放宽，允许使用SSL_CERT_FILE而不强制--native-tls，并新增UV_NATIVE_TLS环境变量与 keyring 凭据支持；
0.1.24：修复用户名含@的认证问题；
0.1.33（破坏性变更）：keyring 凭据查找要求索引 URL 提供用户名，不再默认假设oauth2accesstoken，日志中给出了 Google Artifact Registry 的迁移示例（在 URL 中显式写出https://oauth2accesstoken@<url>）。

网络层的修复同样密集：HEAD 404/403 时的回退（0.1.15、0.1.33）、range request 保留认证（0.1.10）、Artifactory 索引的优雅降级（0.1.4）、HTML 索引的 URL 解码（0.1.3/0.1.15/0.1.17）、以及 Git 依赖改用git命令行而非libgit2以增强 SSH 支持（0.1.7）。HTTP 客户端相关的实现可在 crates/uv-client/ 与 crates/uv-auth/ 中进一步查证。

缓存与解析性能演进

日志中"Performance"小节的出现本身就标志着 uv 将性能作为独立维护目标：

0.1.10：移除版本映射中的spawn_blocking，修复 gzip 响应与 PEP 691（HTML 内嵌版本元数据）处理；
0.1.19：版本区间操作性能改进；
0.1.24：Git ref 内存缓存；引入未命名需求的 PEP 517 构建支持；
0.1.28：预解析阶段统一走 distribution database 与 index，lookahead URL 时填充内存索引；
0.1.30：批量预取加速冷缓存下urllib3-boto3-botocore这类典型依赖链的解析；
0.1.33：包优先级启发式；
0.1.45：解析器并行化（"Parallelize resolver"，#3627），这是该系列最后一次大版本迭代的核心性能动作。

缓存正确性方面，0.1.x 修复了多类问题：构建源分发包时改用缓存目录而非全局临时目录（0.1.5）、缓存损坏时的自愈（0.1.6）、凭据更新不再触发缓存失效（0.1.32）、缓存清理对无读权限目录的健壮性（0.1.43）。CACHEDIR.TAG在 0.1.5 起写入 uv 创建的虚拟环境，便于系统识别缓存目录。

必须留意的破坏性变更

0.1.x 期共有四处值得迁移时注意的破坏性变更（均直接摘自日志原文）：

0.1.18：原生根证书/SSL_CERT_FILE行为改为需显式--native-tls；
0.1.24：uv pip uninstall不再接受-e/--editable形式指定卸载目标（改为直接支持未命名需求）；
0.1.25：overrides 与 constraints 仅限requirements.txt格式，同时 CLI 禁止pip uninstall -r引用pyproject.toml；
0.1.33：keyring 凭据要求 URL 中携带用户名（见上文迁移说明）。

另有一个特殊案例：0.1.44是一个回退发布，撤销了 0.1.43 中"manylinux: auto 启用 musllinux_1_2 aarch64 构建"的变更，因为该改动在构建 aarch64 Docker 镜像时引入了invalid peer certificate: BadSignature类 SSL 错误，日志明确说明恢复 0.1.42 的构建行为。这类"发布记录里的回退"对判断某版本构建产物的可信度很有参考价值。

0.1.40–0.1.45：项目接口的预览期

0.1.40 开始，日志中出现了独立的"Preview features"小节，这条线索实际上就是 uv 项目工作流的胚胎：

0.1.40：tool.uv.sources基础支持（#3263，以 preview 模式启用）、"install from lock file" 初版（#3340）、universal lock file format 初始版本（#3314）；
0.1.42：uv run --with使用环境分层；
0.1.43：uv run项目分层发现、基于项目根读写uv.lock、从pyproject.toml读取包名，并把 workspace API 更名为project API（#3489）；
0.1.45：lockfile 补齐全量分发的哈希与版本（#3589）、registry 源分发包支持（#3649）、registry 文件大小（#3652）、Git 依赖的无损序列化（#3630）、direct URL 与本地路径转换（#3633/#3609）、sourcedist更名为sdist（#3590）。

这些预览功能在 0.2.0 稳定为uv init/uv add/uv sync/uv run与uv.lock体系。当前仓库中的 uv-workspace、uv-resolver（lockfile 读写）等 crate 即承接了这一演进；仓库根目录的 uv.lock 文件本身也是这一机制的实际产物。