uv 0.6.x 版本变更全解：0.6.0 破坏性变更、PEP 751 支持与 Python 版本演进

本篇技术指南基于 uv 仓库中的 changelogs/0.6.x.md 完整梳理 uv 0.6.x 系列（0.6.0 至 0.6.17）的全部变更。你将了解 0.6.0 中 8 项破坏性变更的具体影响与升级应对方式（如 uv init 生成 main.py、UV 环境变量注入、uv pip compile 的 -p 语义调整），0.6.15 引入的 PEP 751 pylock.toml 文件格式的三种使用命令，以及锁文件 revision 字段、Windows 缓存机制改造等底层实现的源码级原理，从而能够安全地从 0.5.x 升级到 0.6.x 并正确使用新能力。

0.6.x 系列概览

0.6.0 是一个带有破坏性变更的版本。按照 uv 的发布节奏，在 0.5.0（上一个含破坏性变更的版本）之后共累积了 31 个发布、1135 个 PR，其中许多改进虽然提升了正确性与用户体验，但可能对部分工作流造成影响。0.6.0 集中承载了这些变更，其中很多被出于谨慎标记为“breaking”，官方预期大多数用户可以不做任何修改直接升级。

0.6.x 系列的版本脉络可以概括为三个阶段：

• 0.6.0：集中落地 8 项破坏性变更，稳定化 uv publish，并新增 PEP 723 脚本环境 --active 支持与锁文件 revision 字段；
• 0.6.1 至 0.6.14：以修复和增强为主，涵盖 UV_PYTHON_DOWNLOADS_JSON_URL 自定义托管 Python 源、--managed-python 简化开关、uv sync --check、构建依赖约束（tool.uv.build-constraint-dependencies）、default-groups = "all"、索引 authenticate 策略等一系列配置能力；
• 0.6.15 至 0.6.17：0.6.15 引入 PEP 751 pylock.toml 的初步支持（该系列最重要的新特性），0.6.16 回滚了一个 302 重定向认证修复，0.6.17 则修复了若干解析 panic 并新增 PyTorch GPU 后端的 v2.7.0 支持。

以下逐节展开，所有条目均与 changelogs/0.6.x.md 原文一一对应。

0.6.0 破坏性变更详解

1. uv init 改为创建 main.py

此前 uv init 会创建 hello.py 示例文件；0.6.0 起改为创建 main.py，以符合用户反馈的普遍预期。如果完全不需要生成入口文件，可以使用 --bare 选项。

从源码看，这一行为落在项目初始化命令中：crates/uv/src/commands/project/init.rs 的初始化流程里，对扁平应用（flat application）会先检查 main.py 是否已存在，不存在则写入默认内容（见该文件第 817 行附近的 // Create main.py if it doesn't exist 逻辑）。0.6.1 的文档更新中还专门加了一条说明，提示 main.py 曾经是 hello.py，便于老用户迁移认知。

2. uv python install 开始尊重 UV_PYTHON

此前 uv python install 不读取 UV_PYTHON 环境变量；0.6.0 起会读取。这一行为更符合用户预期，但注意优先级问题：UV_PYTHON 会优先于 .python-version 文件，这可能打破依赖 .python-version 的工作流，因此被列为破坏性变更。

UV_PYTHON 在 CLI 层被广泛接线：在 crates/uv-cli/src/lib.rs 中，python 系列多个子命令（find、install、pin 等）的选项均通过 env = EnvVars::UV_PYTHON 声明对该环境变量的尊重，可以在源码中逐处对照。

3. 子进程注入 UV 环境变量

当 uv 派生子进程时，现在会在子进程环境中设置 UV 环境变量，其值为 uv 可执行文件的路径。如果你自己也在设置 UV，它的值会被覆盖——这是该项变更的破坏性来源。

一个值得注意的技术细节：该项变更还要求把 uv 的 Rust 入口函数 uv::main 标记为 unsafe，以避免修改进程环境带来的不可靠性（unsoundness）。仅在通过 Rust 直接调用 uv 库的场景下相关。这一声明在当前源码中依然可见：crates/uv/src/lib.rs 中即为 pub unsafe fn main<I, T>(args: I) -> ExitCode。

4. 对不存在的 extras 报错（如 uv sync）

此前 uv 会静默忽略命令行请求的不存在的 extras（如 uv sync --extra foo）。忽略不存在的 extra 在解析第三方包时通常是对的——某个 extra 可能只存在于包的某一兼容版本而非另一版本；但对本地项目没有这种灵活性需求，报错反而更符合直觉。因此 0.6.0 起，针对本地项目请求不存在的 extra 会直接报错。

5. --frozen 下校验依赖组存在性

此前使用 --frozen 标志时，uv 不会校验所请求的依赖组（dependency group）是否存在于锁文件中。0.6.0 起，若请求的依赖组不存在会抛出错误，避免在 CI 等“冻结”场景下静默安装不完整的依赖集。

6. uv pip compile 中 -p 语义统一为 --python 别名

这是 0.6.0 中最微妙的一项。此前在 uv pip compile 中，-p 是 --python-version 的别名，而在 uv CLI 的其他所有地方，-p 都是 --python 的别名；同时 uv pip compile 也不尊重 UV_PYTHON 环境变量。0.6.0 将其语义统一为与其他命令一致。

但 --python-version 有一个特殊语义被保留：如果找不到指定版本的解释器，不会失败，而是使用替代解释器并在解析阶段用请求版本覆盖其版本标签（用于向后兼容）。因此变更后：

• --python <version> / -p <version>：找不到该版本时不会失败（沿用版本覆盖语义）；
• --python <path> 或 --python pypy 这类指定具体解释器的请求：找不到时会以错误退出。

破坏性部分即 UV_PYTHON 开始被尊重，以及 --python <version> 找不到版本时不再失败。

7. 派生 Docker 镜像的 Alpine 默认标签升至 3.21

Alpine 3.21 于 2024 年 12 月发布，并被官方 Alpine 版 Python 镜像使用。uv 的 uv:python3.x-alpine 镜像自 v0.5.8 起已使用 3.21；0.6.0 之后，uv:alpine 镜像从 3.20 升级到 3.21，而 uv:alpine3.20 标签将不再更新。仓库中的 Dockerfile 可作为镜像构建配置的参考起点。

8. Windows 上改用文件指针替代 junction

此前 uv 在 Windows 上使用 junction 实现缓存条目的原子替换；0.6.0 起改为使用一个指向缓存条目的指针文件，解决了 junction 的多种边缘行为问题。这些指针文件仅供 uv 自身消费，且缓存版本号已随之升级。官方认为该变更不影响既有工作流。

稳定化：uv publish 脱离 preview

uv publish 从 preview 状态转为稳定功能，行为本身没有变化——只是不再显示实验性警告。这意味着向 PyPI 发布包的流程（含 0.6.6 修复的网络重试、0.6.15 起上传耗时报告等增强）可以视为正式支持的能力。

其他增强

• 支持 PEP 723 脚本环境使用 --active（在已有脚本环境中激活运行）；
• 锁文件新增 revision 字段，允许向后兼容的元数据变更。源码中可以直接看到其语义定义：crates/uv-resolver/src/lock/mod.rs 中 revision: u32 字段的注释明确写着“revision 变更表示锁文件格式的向后兼容变更；只支持 revision 1 的 uv 版本也能读取 revision 大于 1 的锁文件（可能忽略新字段）”。同文件还定义了 METADATA_FREE_REVISION 常量，用于支持省略包声明元数据的锁文件（(version, revision) >= (1, 1) 判断），这就是 uv.lock 能演进格式而不破坏旧版读取能力的机制基础；
• 修复若干 Bug：避免从 .egg-info 文件读取元数据、在 archive 指针中包含 archive bucket 版本、附加字段动态时省略锁文件版本、uvx --from tool@latest 时尊重可执行文件名等。

文档变更

CHANGELOG.md 自 0.6.0 起拆分为按“主版本”划分的独立文件（即 changelogs/0.6.x.md、changelogs/0.7.x.md 等），以修复渲染问题。你正在阅读的这份文件就是拆分产物之一。

0.6.1 至 0.6.4：稳定性与性能打磨期

这一阶段以 Bug 修复和内部性能优化为主，其中对用户可见的增强值得单独记录。

0.6.1：

• 允许用户把平台标记为“required”以校验 wheel 覆盖率；
• 对非构建配置和非工作区根目录的 pyproject.toml 发出构建警告；
• 修复 uvx --reinstall 提示信息、wheel 下载 HTTP 400 时回退到 GET（Range 请求兼容）、偏好选择中优先本地变体等。

0.6.2：

• 新增 tool.uv.build-constraint-dependencies，支持约束构建依赖的版本；
• 添加新依赖组时对组键排序；
• 性能优化：对 index URL 使用 Arc 共享；
• 修复 x86-64 Python 在 ARM Windows 上的使用、冲突标记可能导致锁文件异常膨胀的问题等。

0.6.3：

• 允许 requirement.txt 文件中命令行选项带引号；
• uv lock --script 支持初始化 PEP 723 脚本；
• UV_ENV_FILE 支持多个 .env 文件；
• 大量性能优化：减少 resolution 转换开销、Hashes 与 Yanked 改用 SmallString/Box、字节码编译复用安装并发度；
• 修复字节码编译跳过已删除目录、Windows 下路径分隔符显示为反斜杠、支持冲突标记的 uv export 等十余项问题。

0.6.4：

• PyPy 3.10 升级至 v7.3.19；
• 支持从 CLI 配置日志详细度（如 -vvv）；
• 单文件中发现重复索引名时警告；
• Bug 修复涵盖：跨 32/64 位发现 Windows 注册表（PEP 514）Python、确认提示中 Ctrl-C 不再 panic、解释器缓存对系统升级保持稳健、wheels bucket 改用 hash 而非完整 wheel 名等；
• 性能方面集中消除字符串克隆与分配（版本包含检查、工具名枚举、包名构造器、SmallString 用于文件名与 URL 等），并再次迁移到 zlib-rs。

0.6.5 至 0.6.9：配置能力与认证策略

0.6.5：

• uvx 支持 --constraints 与 --overrides；uv tool run 的 satisfies 检查支持 overrides；
• 允许在 tool.uv.sources 上设置 package = true；
• uv run 支持 Windows 传统脚本；uvx run 会警告用户；
• 新增 NO_BUILD 与 NO_BUILD_PACKAGE 环境变量；
• Preview：构建后端拆分到独立的 uv_build 包。

0.6.6（Python 发行版相关的重要版本）：

• 支持 x86-64 Linux 上的动态 musl Python 发行版；
• 允许在 Linux 的 Python 3.13/3.14 上运行时启用实验性 JIT；
• 构建工具链升级至 LLVM 20；
• 新增 [index].authenticate 配置，允许为索引强制要求认证；
• uv add 新增 --marker 标志；uv pip install/uv pip compile 新增 pip 兼容的 --group 标志；
• 修复 uv publish 网络失败重试、uv python install --reinstall 等。

0.6.7：

• 内置 CPython 3.14.0a6；修复 Linux 扩展模块误用 CXX 编译器的回归；
• uv add 支持 -c 约束参数；uv python pin 支持 --global 默认版本；
• 修复：默认缓存键加入 src、GraalPy abi 标签解析与发现、uv sync --script 中的冗余脚本包等。

0.6.8：

• default-groups = "all" 支持默认启用所有依赖组；
• 新增更简单的 --managed-python / --no-managed-python 开关。

0.6.9：

• 当 authenticate = "always" 时使用 keyring --mode creds；无密码且 authenticate = "always" 时给出具体错误；
• Preview：--torch-backend=auto 自动推断 PyTorch 索引。

0.6.10 至 0.6.14：工具链能力补齐

0.6.10：

• 新增 uv sync --check：只检查同步状态而不实际执行，适合 CI 校验；
• uv python list 支持版本请求过滤；uv tool run 支持 .env 文件；uv python find --script；
• 修复：--no-build 下的虚拟包、--exclude-newer 从锁文件省略 wheel、requirements.txt 缺失参数报错等。

0.6.11：

• uv export 输出中新增依赖来源注释（"via ..." comments）；
• [[tool.uv.index]] 支持 --find-links 风格的 flat 索引；
• 区分 -q 与 -qq 的详细度级别；
• 新增 UV_PROJECT 环境变量用于设置项目目录；
• 修复 uv sync 尊重构建约束、uv tree --only-group 尊重传递依赖等。

0.6.12：uv python list 报告所查询的可执行文件路径；改进归档解包错误信息；解包归档时强制执行 CRC-32 校验；修复设置文件中 python-platform 的解析。

0.6.13：

• uv python find 新增 --show-version；
• 搜索解释器时跳过 PATH 中的重复目录；
• 新增 UV_PYTHON_DOWNLOADS_JSON_URL，允许自定义托管 Python 下载源（离线/镜像场景有用）；
• 拒绝 uv pip compile -o 输出到 pyproject.toml；--offline 对 Git 操作生效；
• MSRV 提升至 1.84。

0.6.14：

• 同步 CPython 3.13.3、3.12.10、3.11.12、3.10.17、3.9.22；
• uv init --build-backend 新增 uv-build 与 uv_build 别名；
• 对 Conda environment.yml 给出专门的错误信息；
• 修复：系统级配置文件中设置 tool.uv.sources 时报错、uv init 将 workspace members 拆到独立行。

0.6.15：PEP 751 pylock.toml 初步支持

0.6.15 是 0.6.x 系列中特性含量最高的版本，核心是 pylock.toml 文件格式的初步支持——这是由 PEP 751 标准化的替代解析输出格式，目标是取代 requirements.txt（例如 uv pip compile 的场景中，从一组输入需求生成“锁定”的 requirements.txt）。pylock.toml 是标准化、工具无关的格式：未来 uv 生成的 pylock.toml 可以被其他工具安装，反之亦然。

该版本中，pylock.toml 支持以下命令：

# 将 uv.lock 导出为 pylock.toml
uv export -o pylock.toml

# 从一组需求生成 pylock.toml
uv pip compile -o pylock.toml requirements.in

# 从 pylock.toml 安装
uv pip sync pylock.toml
uv pip install -r pylock.toml

实现上，pylock 有独立模块 crates/uv/src/commands/pylock.rs，导出格式抽象位于 crates/uv-configuration/src/export_format.rs，并接线到 pip compile、pip install、pip sync 与 project export 命令中，测试覆盖见 crates/uv/tests/pip_compile/pip_compile.rs 与 crates/uv/tests/project/export.rs。

0.6.15 的其他增强同样密集，择要列举：

• uv.lock 新增上传时间（upload time）字段；
• 允许按名称更新 Git 源依赖；
• uv sync 的 --dry-run 可与 --locked / --frozen 联用；
• uv export 自动推断输出类型；
• uv init 对损坏的 git 环境具备韧性；
• 构建约束对 uv run --with 依赖与 uv tool / PEP 723 脚本生效；
• UV_INDEX 按所有空白字符切分；
• 使用 uvx 二进制名搜索 uv 二进制时的后缀处理；
• 安全相关：凭证调试信息与 URL 日志中对密码/token 做混淆处理；
• 为所有线程设置 4MB 栈大小并引入 UV_STACK_SIZE 环境变量；
• 向子进程转发更多信号（uv run）；SIGINT 发送前加入短暂 sleep；
• 修复 PEP 440 预发布排他比较运算符、aarch64 交叉编译发行版的 sysconfig CC/CXX 补丁等。

0.6.16 与 0.6.17：修复收尾

0.6.16 仅一个修复：回滚 0.6.15 中“正确处理 302 重定向 URL 认证”的变更（该修复引发了回归）。

0.6.17：

• Preview：GPU 后端的 PyTorch 新增 v2.7.0；
• 修复若干解析健壮性问题：无效 Python 版本不再 panic、阻止脚本覆盖 python 可执行名、处理无效重定向时检查发行版名、resolver 线程检查包名与发行版名不匹配、PEP 508 名称末尾非法字符不再 panic；
• 索引页未列出时也拒绝不满足 requires-python 的版本。

升级建议与结论

如果你正从 0.5.x 升级到 0.6.x，按影响面自查以下几点即可覆盖绝大多数破坏性场景：

1. 是否依赖 uv init 生成的 hello.py 文件名（现为 main.py）；
2. 是否自行设置了 UV 环境变量且依赖其值不被覆盖；
3. 是否在 uv pip compile 中把 -p 当作 --python-version 使用（现语义与全 CLI 统一）；
4. 脚本中是否通过 uv sync --extra <不存在> 或 --frozen + 缺失依赖组的方式依赖旧的静默行为；
5. Docker 流水线是否固定使用 uv:alpine3.20 标签（该标签停止更新，uv:alpine 已切换至 3.21）。

0.6.x 系列整体呈现清晰的演进轨迹：0.6.0 完成接口语义统一与格式演进机制（revision 字段）落地，0.6.5 至 0.6.14 补齐构建约束、认证策略、缓存与环境变量等配置面，0.6.15 则以 PEP 751 支持为系列画上特性句号。结合 changelogs/0.6.x.md 原文与上文的源码定位，本文覆盖的每一项变更均可在仓库中直接对照验证。