uv 0.12.0 深度拆解：Python 包管理器的「信任进化」——预发布解析、哈希强制与 pylock.toml 的正确性革命

2026 年 7 月 28 日，Astral 发布 uv 0.12.0。这不是刷版本号的功能大版本，而是一次罕见的「正确性硬化」：15+ 项变更里，绝大多数是在让 uv 拒绝执行原本会「勉强容忍」的操作——拒绝装没有哈希校验的包、拒绝信不过的证书、拒绝格式非法的锁文件、拒绝把包装进错误的环境、拒绝静默跳过坏掉的虚拟环境。本文从预发布解析、哈希校验、PEP 751 锁文件、TLS 信任、环境发现五个主题逐条拆解，附完整迁移实战。

一、背景：Python 包管理的「装得快」与「装得对」之争

过去十年，Python 的依赖管理一直被吐槽「能用但不好用」。问题从来不是装不上，而是装得对不对没人敢保证：

• pip install 把依赖摊在全局 site-packages 里，环境一多就互相踩踏；
• requirements.txt 只记录顶层依赖，锁不住传递依赖，周一的构建和周五的构建可能装出两个世界；
• 想锁版本就得引入 pip-tools 的 pip-compile，但「编译」出来的锁文件没有统一标准，pip 自己反而不认；
• poetry 解决了锁文件问题，但解析慢、侵入性强，还背着「毒瘤」级别的历史包袱（早期版本解析依赖时甚至会在极端情况下死锁）；
• 2024 年之后供应链攻击频繁出现：依赖混淆（dependency confusion）、typosquatting 恶意包、被投毒的知名包，把「装得对」从工程问题升级成了安全问题——你不仅要装对版本，还要确保下载的东西没被人动过手脚。

这个背景下，Astral（ruff 背后的团队）在 2024 年 2 月拿出 uv：一个用 Rust 写的 Python 包管理器，目标是把 pip、pip-tools、virtualenv、pyenv、poetry、pipx、hatchling 一锅端。它最出圈的是快——得益于全局内容寻址缓存、并行下载和 Rust 的零依赖安装，装一个中型项目往往比 pip 快 10~100 倍。快，让它两年内横扫了 Python 工具链市场，成为事实上的「下一代默认」。

但快只是入场券。当一个工具成为千万开发者的默认依赖入口，它真正要交付的就不再是性能，而是信任：解析结果要可复现，下载内容要可校验，失败要失败得明明白白，绝不能「警告一声然后照做」。uv 0.12.0 就是这份答卷。

二、uv 是谁：一个二进制吃掉整个 Python 工具链

先对齐一下 uv 的版图，否则后面聊 0.12 的变更会缺少坐标系。

uv 是一个单体二进制，通过子命令覆盖了工具链的每一环：

它的架构可以抽象成四层：

1. 解析器（resolver）：基于 PubGrub 算法（与 Dart 的 pub 同源），把 pyproject.toml / requirements.txt 的约束解析成一份完整、可复现的版本组合，输出锁文件。PubGrub 的优势是增量解析：改一个依赖时不用全量重算，而且失败时能给出「为什么无解」的冲突链。
2. 安装器（installer）：并行下载 wheel/sdist，校验哈希与尺寸后装入目标环境；同一份包在全局缓存里只存一份，通过硬链接进各个 venv，装 50 个环境不重复占磁盘。
3. 全局缓存（cache）：内容寻址存储，按内容哈希组织，天然去重；uv cache prune 可清理。
4. 运行时层：托管 Python 解释器安装（含 3.13/3.14 等版本、自由线程 build）、构建后端（uv_build，hatchling 的 Rust 重写）、PEP 723 内联脚本元数据支持、uv run 直接执行带依赖声明的脚本。

版本节奏上，uv 长期停留在 0.x（1.0 一直没憋出来），但迭代极快：0.11.0 在 2026 年 3 月发布，到 7 月 28 日 0.12.0 落地，中间光 0.11.3x 系列就打了三十多个补丁版本。0.12.0 的官方定位很直白：

"Since we released uv 0.11.0 in March, we've accumulated changes that improve correctness, safety, and compatibility with specifications, but could break some workflows. This release contains those changes; many have been marked as breaking out of an abundance of caution."

翻译一下：过去四个月攒了一批「提升正确性、安全性、规范兼容性，但可能破坏某些工作流」的变更，这次一起发出来；大部分标记为 breaking 是出于谨慎，多数用户升级不需要改任何东西。 这是典型的「功能稳定期」发布——不画新饼，把欠的债还掉。

下面按主题逐条拆解这些变更。你会发现它们有一个共同的内核：把「静默容忍」改成「显式失败」。

三、主题 A：预发布版本解析——if-necessary 成为默认

这是 0.12.0 里对日常开发影响最大的一条，值得最先讲。

旧行为的反直觉坑

假设你的项目依赖 NumPy 的某个预发布特性，写了：

[project]
dependencies = [
    "numpy>=2.0.0b1",
]

在 0.12 之前的 uv 里，这条依赖直接解析失败——即使 PyPI 上明明存在 2.0.0b1 及更新版本。原因：uv 的预发布策略默认「显式或必要时才允许」，而当时的实现里，传递依赖中的预发布约束不会被考虑。你必须在 pyproject.toml 里把 numpy 作为直接依赖显式声明，或者用 --prerelease allow 放开整个依赖图的预发布开关——一刀切，副作用巨大。

这个行为对「只想尝鲜一个包的 beta」的开发者极不友好，也跟 pip 的行为不一致（pip 对传递依赖里的预发布约束是宽容的）。

新行为：先稳定、后预发布

0.12.0 把默认模式改为 if-necessary（必要时才用）：

1. uv 优先尝试稳定版本；
2. 当没有任何稳定版能满足当前全部约束时，回退到预发布版本；
3. 这一规则同时作用于直接依赖与传递依赖。

于是 numpy>=2.0.0b1 这种声明现在能正常解析：没有稳定版满足 >=2.0.0b1（因为 2.0.0b1 本身是预发布）时，自动落到预发布候选。如果你同时显式写了 numpy>=2.0，那稳定版 2.0.x 优先，预发布根本不会进场。

模式对照

命令层面：

uv add --prerelease disallow "numpy>=2.0"    # 生产依赖：禁用预发布
uv add --prerelease allow "polars"           # 全局允许（慎用）
uv add --prerelease explicit "polars>=1.0.0rc1"  # 只对显式声明的预发布放行
uv lock --prerelease disallow                # 重新锁定时收紧

旧的 if-necessary-or-explicit 模式名保留为别名但已标记弃用，会在未来版本移除。迁移注意：当稳定版和预发布同时满足约束时，0.12 可能选出与旧版本不同的版本——如果 CI 里锁文件是用 --frozen 的，不受影响；如果习惯不提交锁文件，升级后请重新 uv lock 并 diff 一下。

四、主题 B：哈希校验——从「警告一声」到「拒绝执行」

哈希校验是供应链防篡改的第一道防线：安装前用声明的哈希比对下载内容，防止 PyPI 或中间人给你塞进被篡改的包。uv 0.12 把这条防线从「装饰品」变成了「实弹」。

B.1 --require-hashes 指令被强制执行（#19336）

requirements.txt 里可以写 --require-hashes 指令，声明「本文件内所有包必须带哈希」：

--require-hashes
anyio==4.0.0 --hash=sha256:xxx...

旧行为（危险）：uv pip install / uv pip sync 读到这个指令时只打一条警告，然后照常安装、不校验任何哈希。也就是说，安全团队精心维护的哈希清单形同虚设——攻击者只要替换 PyPI 响应（或依赖一个被攻破的镜像），就能绕过所有校验。

新行为：指令在文件内出现即进入 hash-checking 模式，与命令行传 --require-hashes 完全等价，且指令存在期间无法关闭。下面这种「声明了要校验、却既没锁版本也没给哈希」的文件会被直接拒绝：

--require-hashes
anyio

报错理由：anyio 既未固定版本（==），也未提供哈希。正确姿势是把每个包都钉死并提供哈希：

--require-hashes
anyio==4.0.0 \
    --hash=sha256:1c1d13beacb1f9a2c8c5b1d2e6f4e9b3f1a0c2d3e4f5a6b7c8d9e0f1a2b3c4d5e

B.2 MD5-only 哈希被拒绝（#20758）

更细的一条：hash-checking 模式下，如果某个包只有 MD5 哈希，直接拒绝。

anyio==4.0.0 --hash=md5:420d85e19168705cdf0223621b18831a   # 0.12 起：拒绝

理由很硬核：MD5 已不具备碰撞抗性（collision resistance），2004 年就有实用碰撞攻击，2017 年更是可以做到「选择前缀碰撞」。一个攻击者能构造出与合法文件 MD5 相同的恶意 wheel，哈希校验就失去了意义。pip 早就不允许 hash-checking 模式下用 MD5-only，uv 这次是补齐对齐。

新规则：每个包至少需要一个安全摘要（SHA-256、SHA-384、SHA-512 等）。安全哈希可以直接写在 requirement 行上，也可以写在匹配的 constraints 文件里。注意：不带 --require-hashes 的普通安装仍然支持 MD5——这属于「有校验比没有强」的宽容场景，与「强制校验」严格区分。升级动作：把 MD5 换成 SHA-256 重新生成即可，uv pip compile --generate-hashes 可以一键生成全套安全哈希。

这条变更的意义在于：哈希校验不再是可以被「静默降级」的软约束。安全策略一旦声明，就必须被完整执行——这正是企业安全审计最需要的行为。

五、主题 C：pylock.toml（PEP 751）——标准锁文件的严格化

C.1 什么是 PEP 751

Python 生态长期缺乏官方锁文件标准：poetry 有 poetry.lock，pip-tools 产出 requirements.txt，uv 早期用自家 uv.lock，互不兼容。2025 年，PEP 751 被接受，定义了官方锁文件规范 pylock.toml，目标是让 pip、uv、其他工具都能读写同一份锁文件。uv 是最早落地该规范的生态主力之一——此前版本已支持读写 pylock.toml，0.12.0 则把校验补全了，让它从「能读」变成「严格读」。

C.2 三项严格校验

① packages 数组必须存在（#20402）

这是最惊悚的一条。pylock.toml 的规范要求 packages 数组必须出现；而旧版 uv 遇到缺失 packages 的锁文件时，会把整个文件当成「空锁文件」处理。后果：uv pip sync 会认为环境里什么都不该有，把现有环境里的包全部卸载！

# 旧版 uv：这个文件被当成空锁文件 → uv pip sync 可能清空你的环境
version = "1"

# 新版 uv：直接报错，拒绝执行

一个格式错误的锁文件 + 一条 sync 命令 = 环境被清空。这种「解析错误被静默降级为业务逻辑」的 bug 是数据销毁级的。0.12 起，缺失 packages 数组直接拒绝执行；显式声明 packages = [] 的空锁文件仍然合法（这是有意的空环境声明）。

② 锁文件名必须规范（#20440）

pylock.toml 是标准名；pylock.dev.toml 这类单段变体也合法（用于区分 dev/生产锁）。但 pylock..toml、pylock.foo.bar.toml 这种多段/空段命名一律拒绝——防止工具链对变体命名的解析产生歧义。

③ 构件尺寸必须匹配（#20443）

如果锁文件里声明了 wheel/sdist 的 size，那么下载或缓存命中后的实际大小必须一致。以前「哈希对就行、尺寸错了也接受」；现在尺寸不一致就是失败。索引服务器上报的尺寸仍是参考值，但锁文件里固化下来的尺寸是承诺，必须兑现。这防的是「哈希碰巧一致但内容被替换」的边角场景（虽然哈希一致已极难，但纵深防御不嫌多）。

C.3 迁移动作

这些校验无法关闭。遇到报错，正确姿势是重新生成锁文件：

uv lock                # 重新解析并生成 pylock.toml（或 uv.lock）
uv lock --upgrade      # 顺带升级依赖

文件名不合规就改名：

mv pylock.foo.bar.toml pylock.toml

六、主题 D：TLS 信任——从 fail-open 到 fail-closed

企业内网经常要用自建 PyPI 镜像 + 自签 CA，配置方式是通过环境变量指定 CA：

export SSL_CERT_FILE=/etc/ssl/company-ca.pem
export SSL_CERT_DIR=/etc/ssl/company-ca.d

旧行为（fail-open，危险）：如果 SSL_CERT_FILE / SSL_CERT_DIR 指向的路径不存在、不可读、是空文件/空目录、或里面没有合法证书，uv 会忽略这个配置，悄悄回退到系统默认信任库。后果：管理员以为流量只信任公司 CA（意味着可以拦截审计、拒绝外部证书），实际上 uv 照样信任公共 CA——HTTPS 连接了本应被拒绝的站点，TLS 策略形同虚设。更糟的是这一切是静默的，没人会注意到。

新行为（fail-closed）：任何非空的 SSL_CERT_FILE 或 SSL_CERT_DIR 值都会替换 uv 的默认信任根；如果这些路径加载不出任何合法证书，HTTPS 请求直接失败（因为一个证书都不被信任）。影响范围覆盖包下载和远程脚本执行（包括从 GitHub Gists 拉取脚本）。

# 配置指向了不存在的文件 → 0.12 起：所有 HTTPS 请求失败（而非悄悄用公共 CA）
export SSL_CERT_FILE=/etc/ssl/company-ca.pem   # 文件不存在
uv pip install requests
# error: failed to download... certificate verify failed

修复方式：修正路径让 CA 可加载；或者 unset SSL_CERT_FILE 恢复默认信任库（空字符串值仍会被忽略，等于没设置）。

配套的还有一个 pip 兼容能力：uv pip 支持 --cert 参数（#20418）：

uv pip install --cert ./company-ca.pem requests

语义与 pip 一致：该 PEM bundle 完全取代本次调用里的其他所有证书来源（系统证书、SSL_CERT_FILE/SSL_CERT_DIR 都不再参与）。注意 --cert 只对 uv pip 子命令生效，其他 uv 命令继续走环境变量配置；bundle 里要包含必要的完整 CA 链。

这两个变更合起来，把「证书配置」从「建议」变成了「契约」：你配置了什么，就信任什么；配置坏了，宁可全断也不裸奔。 这正是安全默认值（secure by default）的教科书写法。

七、主题 E：环境发现——消灭「装错环境」的静默错误

Python 项目最怕的不是装不上，而是装进了错误的环境还毫无察觉。0.12 在这个维度上修了一串「静默错位」：

E.1 坏掉的 .venv 符号链接立即报错（#20433）

场景：项目目录里有个指向已删除目录的坏 .venv 软链。旧版 uv 发现它「不能用」后，跳过它继续向父目录搜索另一个虚拟环境——结果 uv pip install 可能把包装进了某个祖先项目的环境里！等到发现时，要么污染了别人的环境，要么白装半天。0.12 起：遇到坏 .venv 软链立即停止并报告确切路径；读取虚拟环境元数据出错（含权限问题）同样立即上报，不再忽略。此行为不可关闭，修复方式就是删掉/修好软链。

E.2 脚本按自身所在项目解析（#20225）

uv run other-project/script.py

旧行为：从当前目录向上发现项目——哪怕脚本属于隔壁项目，也会用当前项目的依赖去跑它，导致「脚本自己的依赖没装」这类诡异失败。新行为：从脚本所在目录开始项目/工作区发现，other-project/script.py 就用 other-project 及其依赖。想强制回到当前目录，显式指定：

uv run --project . other-project/script.py

这条稳定了 target-workspace-discovery 预览特性，属于「少一个隐性心智负担」的修复。

E.3 uv venv --clear 拒绝清非虚拟环境目录（#20225）

uv venv --clear ./some-important-dir   # 0.12 起：拒绝

旧行为：--clear 会删掉目标目录里的一切，哪怕它根本不是虚拟环境——只打一条警告就动手，误删源码目录的风险极大。新行为：目录里没有虚拟环境就拒绝删除；确实要清，加 --force：

uv venv --clear --force ./not-a-virtualenv

E.4 Conda 的 base/root 特殊名按路径识别（#20225）

Conda 环境叫 base 或 root 时，旧版 uv 一律当成「Conda 根环境」，即使它们只是普通子环境。现在按路径判断，子环境不再被误认。想绕开自动解释器选择，用 --python /path/to/python 显式指定。

E.5 --project 严格化（#20225）

• uv init --project example 变成报错（--project 是给已存在项目用的；初始化用 uv init example 或 uv init --directory example）；
• uv run --project missing python 这种指向不存在目录/非 pyproject 文件的用法立即失败，不再警告后继续瞎跑；
• 传 --project path/to/pyproject.toml 仍然合法，等价于选择其父目录。

E.6 uv python install --reinstall 语义修正（#20659）

以前 uv python install 3.12 --reinstall 兼任「装最新 3.12 补丁版」；有了正式的 --upgrade 后，--reinstall 回归本义：重装本地已匹配的补丁版本。比如本机装了 3.12.6 和 3.12.7，--reinstall 会把两个都重装；要升级到最新补丁版用 uv python install 3.12 --upgrade；组合 --upgrade --reinstall 表示「只重装最新补丁」。语义清晰了，CI 里自动装 Python 的脚本请改用 --upgrade。

E.7 --upgrade-group 必须指向真实存在的依赖组（#18957）

uv lock --upgrade-group docs 如果项目里根本没有 docs 这个 dependency group，旧版静默成功（什么都没升级，你还以为升级了）。现在直接报错。兼容性说明：tool.uv.dev-dependencies 这种旧式写法仍能满足 --upgrade-group dev。

E.8 相对路径语义修正（#20740、#18402）

• --index / --extra-index-url / --find-links 等相对路径，现在相对 --directory 指定的目录解析（此前相对原始工作目录，行为分裂）；
• uv add 的绝对路径参数原样保留，不再被改写。

八、主题 F：发布与构建后端

• uv publish 跳过非规范化文件名的构件：wheel/sdist 文件名必须用规范化的包名与版本（1.01.0 版要叫 example-1.1.0-py3-none-any.whl，不能叫 example-1.01.0-...）。旧版警告后照传，现在直接跳过——避免把不规范构件污染进索引。
• uv init 默认声明构建系统：新建项目默认带 [build-system] 并按「可打包项目」布局生成（#19197）。对纯脚本项目不友好？可以 uv init --no-package（如果你在用旧版布局，升级后 uv init 产物会变，注意 CI 里若有「假设新项目不可打包」的逻辑）。
• 拒绝可能替换 Python 解释器的 wheel（#20748/#20749）：防止恶意/异常 wheel 通过安装覆盖解释器本体，属于安装安全边界。

构建后端兼容性方面，官方明确：uv_build 的配置没有破坏性变更。唯一要注意的是如果你的 [build-system] 里对 uv_build 设了上界，需要放开到 0.12：

[build-system]
requires = ["uv_build>=0.11.32,<0.13"]
build-backend = "uv_build"

九、架构视角：为什么 uv 能「变严」而不「变慢」

安全硬化最容易的代价是性能。uv 0.12 的巧妙之处在于，所有新增校验都落在「缓存之前」或「缓存命中路径上」，没有破坏内容寻址缓存带来的性能红利：

• 解析层：预发布策略只是候选排序的变化，PubGrub 增量解析不受影响；
• 下载层：哈希/尺寸校验是下载完成时的必经步骤，校验通过的内容进入全局缓存，缓存命中时不再重复校验（内容寻址本身保证一致性）；
• 锁文件层：schema 校验是解析 TOML 时的常数级开销；
• TLS 层：证书加载是一次性的，连接复用不受影响。

一个值得注意的例外是 0.11.33（0.12.0 发布当天同步放出）引入的预览特性：缓存复用前对锁定的工具做 malware 检查（#20301）。它在「缓存命中 → 直接复用」这条快路径上插了一道安全闸，意味着 uv 开始认真对待「缓存本身被投毒」的场景——代价是缓存命中变慢一点点，换来的是供应链纵深。同批预览还有 uv check --script（只检查脚本）和「无 package.metadata 的锁文件读写」。这些预览特性在 0.12 系列会逐步稳定，方向很清楚：安全校验正在从「下载时」前移到「复用前」。

十、实战：把项目平滑升级到 uv 0.12

10.1 升级与验证

# 方式一：官方安装脚本（幂等，会覆盖旧版本）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方式二：已装过 uv，直接自升级
uv self update

# 方式三：Homebrew / pipx / GitHub Actions 的 setup-uv
brew upgrade uv
uv --version   # 确认 0.12.0

升级后先跑一遍现有工作流，重点观察三类报错：锁文件/哈希相关（说明你踩中了新校验）、--project 相关（参数语义收紧）、.venv 相关（环境发现更严格）。

10.2 迁移检查清单

10.3 CI 集成（GitHub Actions）

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v7
        with:
          version: "0.12.0"
          enable-cache: true          # 复用全局缓存
          cache-dependency-glob: "pylock.toml"
      - run: uv sync --frozen --no-dev   # 严格按锁文件，禁止漂移
      - run: uv run pytest

要点：--frozen 保证 CI 永远用锁文件里固化的版本组合，0.12 的严格校验在这里是加分项——任何锁文件漂移都会让 CI 当场失败，而不是悄悄装出不同版本。

10.4 Docker 多阶段构建

FROM ghcr.io/astral-sh/uv:0.12 AS builder
WORKDIR /app
COPY pyproject.toml pylock.toml ./
RUN uv sync --frozen --no-dev --no-install-project

FROM python:3.14-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY app.py .
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]

借助 uv sync --no-install-project + 分层缓存，依赖层只在锁文件变化时重建；0.12 对锁文件的严格校验保证了「CI 里能 sync 的，Docker 里一定也能」。

十一、安全全景：0.12 之后，你的依赖链有多硬

把 0.12 的变更放进威胁模型里看：

还有一道没补上的防线值得清醒认识：wheel 签名验证。哈希校验防的是「传输中篡改」，防不了「发布者自己就是恶意的」（PyPI 账号被盗、恶意发布）。PEP 480/458 的签名方案在生态里推进缓慢，目前没有主流工具默认强制验证签名。uv 的答案是用 uv audit（漏洞扫描）+ 预览中的 malware 检查做补充，但供应链安全的最后一公里（内容签名）仍是全行业未竟之业。别因为工具变严就放松警惕：私有源 + 哈希 + 最小依赖原则，永远比任何单一工具可靠。

十二、总结与展望

uv 0.12.0 值得被认真对待，不是因为它加了什么炫酷功能，而是因为它重新定义了包管理器的默认值：

1. 解析从「一刀切放行」走向「先稳定、必要时才预发布」，与 pip 对齐；
2. 校验从「警告但照做」走向「声明即执行」，--require-hashes、MD5 拒绝、pylock 严格化、尺寸校验，一条条把「软约束」变成「硬约束」；
3. 信任从「fail-open」走向「fail-closed」，证书配置坏了宁可全断也不裸奔；
4. 环境从「静默错位」走向「显式失败」，装错环境的隐患被逐项消灭。

合起来看，这是一次从「性能颠覆者」到「可信默认值」的身份切换——当一个工具成为生态默认，它最大的敌人就不再是别的工具，而是自己曾经的宽容。0.12.0 的每个 breaking change，本质上都是在说：我宁愿让你在 CI 里当场看到红叉，也不愿让错误悄悄溜进生产。

展望未来，两条主线清晰可见：一是 pylock.toml（PEP 751）的生态统一——uv 已经把校验做扎实，pip 侧也在跟进，Python 包管理有望第一次拥有「pip 和 uv 共读一份锁文件」的互通时代；二是安全校验的前移——从下载时校验到缓存复用前扫描、再到（未来的）签名验证，uv 正在把「安装器」改造成「供应链安全网关」。对团队的建议很简单：升级到 0.12，把哈希生成纳入 uv pip compile 流程，锁文件提交进 Git，CI 用 --frozen，然后把 SSL 证书配置检查写进你的环境自检脚本。 这些动作加起来，能让你的依赖链在 2026 年这个供应链攻击频发的节点上，硬上一个档次。

（本文基于 uv 0.12.0 官方 Release Notes（2026-07-28 发布）撰写，命令与行为描述以实际版本为准。）