企业官网建设流程全解析

• 包管理器
• 开发工具
• CLI

导读

本文围绕 pnpm 仓库中的 changeset（.changeset/skip-unreadable-python-requirements.md）展开，剖析 pnpm 对 Python 生态（PEP 508Requires-Dist声明）的一项容错设计：当某个 Python 发行版的 wheel 元数据中声明了一条 pnpm 无法解析的依赖时，安装不再整体失败，而是跳过该发行版、在其余版本中继续求解；仅当所有版本都不可用时，才把"不可读的依赖"作为错误报告出来。读完本文，你将理解 pnpm 在源码层面如何区分"坏掉的一个 wheel"与"pnpm 未实现的能力"，以及这一策略如何在解析器、索引页与锁定环节中保持一致。

一、问题的起点：一条不可读的Requires-Dist曾会中断安装

在 pnpm v12 的 Python 垂直集成中（见 pnpm/plans/PYTHON_SPIKE.md），pnpm 会读取每个 Python 发行版 wheel 的METADATA文件，从中提取四类字段：name、version、requires-dist、requires-python与provides-extra（实现见 pnpm/crates/python-resolver/src/metadata.rs）。其中requires_dist是 PEP 508 格式的依赖声明列表，解析器需要把每一条都解析成结构化依赖才能参与版本求解。

问题在于：wheel 一旦发布就不可变。某个发行版只要有一个 wheel 的元数据里存在 pnpm 无法解析的Requires-Dist（例如语法错误Requires-Dist: >=1 helper），旧行为会让整个安装失败——哪怕索引里还有其他完全正常的版本可用。这等于让一个坏 wheel 把该包的所有版本都拖下水。

对应的 changeset 明确描述了修复语义：

A Python release whose wheel metadata declares a requirement pnpm cannot read no longer fails the install. pnpm now resolves the project against the other releases of that package, and reports the unreadable requirement when none of them works.

即：安装不再因单个坏发行版而失败，pnpm 会改用该包的其他发行版继续求解；只有当所有版本都不可用时，才把不可读的依赖作为失败原因报告。该变更以 patch 级别作用于pacquet与@pnpm/pnpr两个包。

二、修复的核心思想：把"坏发行版"当作不可用版本交给求解器

整个解析流程由 pnpm/crates/python-resolver/src/lib.rs 组织：调用方（pnpm CLI 下载 wheel 后交给解释器读取，或 pnpr 服务器直接读索引元数据）负责所有网络获取，而python-resolvercrate 只负责"规则"——用一次 pubgrub 求解（step）要么解出项目，要么点名还缺什么。

修复的关键改动在 pnpm/crates/python-resolver/src/resolve.rs 的unusable_release函数：

fn unusable_release( refusal: Refusal, ) -> std::result::Result<Dependencies<Package, Ranges<Version>, String>, Needed> { match refusal { Refusal::Unreadable(error) => Ok(Dependencies::Unavailable(format!( "because its metadata declares a requirement pnpm cannot read: {error}", ))), Refusal::Unsupported(requirement) => Err(Needed::Invalid(format!( "unsupported scheme in direct URL Python requirement: {requirement}", ))), } }

可以看到策略被一分为二：

• Refusal::Unreadable（读不懂）→Dependencies::Unavailable：pubgrub 把该发行版标记为"不可用版本"，求解器自然会跳过它、尝试该包的其他版本——这正是"resolve against the other releases"的实现方式。
• Refusal::Unsupported（能解析但 pnpm 不实现）→ 直接报错：这类依赖不是某个 wheel 的偶然错误，而是 pnpm 尚未实现的能力，任何声明了它的发行版都会命中，跳过毫无意义。

三、源码级机制：Refusal如何区分"读不懂"与"不支持"

这一对区分在 pnpm/crates/python-resolver/src/candidates.rs 中完成。read_requirement先把一行声明解析为 PEP 508Requirement：

• 解析失败 →Refusal::Unreadable，说明这一行来自某个坏 wheel；
• 解析成功但直接 URL 的 scheme 不在http、https、git+https、git+ssh、git+file之列 →Refusal::Unsupported，说明这是 pnpm 解析得到但不实现的 scheme。

pub(crate) enum Refusal { Unreadable(miette::Report), Unsupported(String), }

随后 resolve.rs 的metadata_requirements逐条读取某个 wheel 的全部依赖，并保证顺序无关性：只要出现一条Unsupported，立即返回错误；多条Unreadable则只保留第一条，最后统一按Unreadable处理。函数注释点明了原因："A requirement pnpm does not implement outranks one it cannot read wherever the two appear, so what a release costs a project does not depend on the order its metadata happens to list them in."（pnpm 未实现的依赖优先于读不懂的依赖，且与元数据中的声明顺序无关。）

同一个容错思路也贯穿索引页与Requires-Python：

• 索引页层面，candidates.rs 的usable/unusable会把读不懂的文件（无 SHA-256、非 HTTP URL、无法解析的文件名等）直接剔除，而不是让整个页面失败，注释明确写道"一个不可变的旧发行版没有理由阻止项目安装它要的版本"；
• Requires-Python层面，requires_python.rs 把无法解析的Requires-Python视为不存在（declared_range返回None），该文件仍是候选——这与 pip 的行为一致，因为拒绝它会把依赖彻底挡在项目之外。

四、测试如何验证"坏发行版让位，全部坏掉才报错"

pnpm/crates/python-resolver/src/tests.rs 中有两组测试与本次变更一一对应，可作为行为契约：

场景一：只有一个版本坏掉，解析落到更老的可用版本。

a_release_whose_requirements_cannot_be_read_gives_way_to_one_that_can（tests.rs）构造了一个demo包：2.0.0声明了不可读的Requires-Dist: >=1 helper，1.0.0正常。最终step返回Step::Solved，求解结果选中1.0.0——项目成功解析，而不是失败。

场景二：所有版本都读不懂，才把原因报给用户。

a_project_whose_every_release_is_unreadable_reports_why（tests.rs）让唯一一个版本携带同样的坏声明，断言错误信息包含"requirement pnpm cannot read"字样——这正是 changeset 中 "reports the unreadable requirement when none of them works" 的直接验证。

此外还有一个反向测试an_unsupported_url_requirement_is_refused_rather_than_skipped（tests.rs）：对helper @ file:///helper-1.0.0-py3-none-any.whl这种 pnpm 不支持的 scheme，无论它单独出现、与坏声明混排、还是顺序颠倒，都会报unsupported scheme in direct URL Python requirement而不是悄悄降级到旧版本——防止"为了求解而静默安装旧版本"。

五、对使用者的实际影响

对本变更的实际影响可总结为三点：

1. 安装鲁棒性提升：索引或元数据中存在个别坏 wheel 不再让pnpm install直接失败，解析器会自动退而求其次，选择该包其余可用的版本；
2. 错误报告更精确：只有当该包所有版本都不可用时，你才会看到形如because its metadata declares a requirement pnpm cannot read: ...的错误，且你能据此判断是某个发行版自身的问题；
3. 能力边界不被掩盖：真正属于"pnpm 尚未实现的依赖形式"（如不支持的 URL scheme）会立即报错，不会因为容错机制被静默忽略。

六、小结

从 .changeset/skip-unreadable-python-requirements.md 出发，可以完整还原 pnpm 在 Python 解析器中的一条容错设计主线："读不懂的依赖"被降级为"该版本不可用"交给 pubgrub 处理，而"不支持的能力"被升级为硬错误。前者让坏 wheel 从整个包的问题退化为单个版本的问题，后者保证了 pnpm 不会在能力不足时偷偷安装旧版本。这一策略在索引页候选过滤、Requires-Python解析与 wheel 依赖求解三个层面保持一致，并由 tests.rs 中的场景化测试固定下来——既符合 pip 的既有行为惯例，也符合"发布物不可变"的 Python 生态现实。

• 包管理器
• 开发工具
• CLI