pnpm 修复锁文件弃用标记丢失：解析结果未变时保留 `deprecated` 元数据的实现解析

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

导读

本文围绕 pnpm 仓库中的一个 changeset（.changeset/preserve-unchanged-package-metadata.md）展开，深入讲解 pnpm 的一项关键修复：当依赖的解析结果（resolution）未发生变化时，锁文件条目不能再因为 registry 元数据返回不一致而丢失已记录的deprecated（弃用）标记。文章先说明该 bug 的复现场景与危害，再基于 TypeScript 与 Rust 双实现的源码与测试用例，逐层还原修复原理，最后给出可操作的验证方法与最佳实践。读完本文，你将理解 pnpm 锁文件元数据合并的底层逻辑，掌握如何排查"弃用标记静默消失"类问题，并学会用最小复现工程验证修复行为。

一、问题背景：一次"无害"的重新解析，为何会丢掉弃用信息

pnpm 在每次安装时都会把 registry 上拉取到的最新包元数据（metadata）与既有的pnpm-lock.yaml进行合并。锁文件条目的更新逻辑位于 pnpm11/installing/deps-resolver/src/updateLockfile.ts 中的updateLockfile函数，它负责把解析阶段产生的依赖图（dependenciesGraph）与旧锁文件快照（prevSnapshot）重新合并成新的锁文件。

合并过程中，绝大多数字段都直接取自本次解析到的新元数据：

if (pkg.additionalInfo.deprecated) { result['deprecated'] = pkg.additionalInfo.deprecated }

问题就出在这里：deprecated是已发布版本中唯一可以被 registry 侧"事后修改"的字段（源码注释明确写着"deprecatedis the only registry-mutable field of a published version"）。也就是说，同一个版本号的包，某次请求 registry 返回deprecated信息，另一次可能由于 CDN 缓存、镜像源不一致等原因就不返回了。

当 registry 元数据"不一致地"（inconsistently）提供服务时，会出现这样的灾难链：

1. 旧锁文件里已经记录了deprecated标记（例如包作者弃用了某个版本）；
2. 本次重新安装时，registry 恰好没有返回该字段；
3. 由于字段直接覆盖，旧锁文件中的弃用信息被静默抹掉；
4. 锁文件更新后，团队其他人再也看不到该版本的弃用警告。

这正是 changeset 中提到的上游问题 pnpm/pnpm#13846 所描述的场景：解析结果明明没变，弃用标记却被悄悄删掉。弃用信息对工程安全至关重要——它往往是版本存在安全漏洞、bug 或已停止维护的直接信号，丢失后团队可能继续使用已弃用版本而不自知。

二、修复核心：解析未变时，回退到旧快照的弃用标记

2.1 修复后的合并逻辑

修复后的逻辑位于 pnpm11/installing/deps-resolver/src/updateLockfile.ts，采用"新元数据优先、旧快照兜底"的策略：

if (pkg.additionalInfo.deprecated) { result['deprecated'] = pkg.additionalInfo.deprecated } else if ( // `deprecated` is the only registry-mutable field of a published // version; an unchanged resolution must not lose a recorded // deprecation to a registry serving it inconsistently // (pnpm/pnpm#13846). opts.prevSnapshot?.deprecated != null && equals(opts.prevSnapshot.resolution, lockfileResolution) ) { result['deprecated'] = opts.prevSnapshot.deprecated }

这段代码的语义可以拆成三个分支理解：

• 新元数据带了弃用信息：直接采用，result['deprecated'] = pkg.additionalInfo.deprecated；
• 新元数据没有弃用信息，但旧快照有，且两次解析结果完全一致：从opts.prevSnapshot.deprecated回退恢复弃用标记；
• 其他情况（新旧元数据都无弃用信息，或解析结果发生了变化）：不写deprecated字段。

其中第二个分支是本次修复的关键，它依赖两个前提条件的联合判断：

equals(opts.prevSnapshot.resolution, lockfileResolution)这一比较是整个修复的"安全阀"：它确保我们只在解析结果未变化时才信任旧快照的弃用标记。一旦包的版本或解析方式变了（比如 integrity 变化、从 tarball 换成了别的来源），就必须以 registry 最新返回的元数据为准，避免张冠李戴。

2.2 为什么这个修复是安全的

从源码结构看，该修复刻意将"旧弃用标记的恢复"限制在"解析未变"这一狭窄窗口内，理由有二：

1. deprecated的注册表可变性：它不像版本号、依赖列表那样在发布后不可变更，registry 随时可能更新或撤销弃用状态，因此新元数据缺失时不能简单地当作"不再弃用"；
2. 版本错配风险为零：resolution相等意味着 tarball、integrity、版本来源全部一致，恢复旧标记不会污染其他版本的条目。

三、测试验证：两条用例锁定的行为边界

修复是否可靠，测试是最直接的证据。在 pnpm11/installing/deps-resolver/test/updateLockfile.test.ts 中新增了两条针对性用例：

用例一：解析未变时保留弃用标记

test('an unchanged resolution never loses its recorded deprecation to metadata drift', () => { const lockfile = updateLockfile({ dependenciesGraph: tarballGraph({ tarball: TARBALL_URL, integrity: INTEGRITY }), lockfile: lockfileWith({ resolution: { tarball: TARBALL_URL, integrity: INTEGRITY }, deprecated: 'No longer maintained', }), prefix: '.', registriesByScope: REGISTRIES, }) expect(lockfile.packages![DEP_PATH].deprecated).toBe('No longer maintained') })

该用例构造了一个"新元数据完全不含deprecated字段"的依赖图（tarballGraph中只给了 tarball 与 integrity），而旧锁文件（lockfileWith）中记录了deprecated: 'No longer maintained'且 resolution 完全一致，最终断言新锁文件中弃用标记仍然保留。

用例二：解析变化时以新元数据为准

test('a changed resolution takes the freshly served metadata', () => { const newIntegrity = 'sha512-CccC...' const lockfile = updateLockfile({ dependenciesGraph: tarballGraph({ tarball: TARBALL_URL, integrity: newIntegrity }), lockfile: lockfileWith({ resolution: { tarball: TARBALL_URL, integrity: INTEGRITY }, deprecated: 'No longer maintained', }), prefix: '.', registriesByScope: REGISTRIES, }) expect(lockfile.packages![DEP_PATH].deprecated).toBeUndefined() })

这条用例把 integrity 从旧值换成了新值，导致resolution不再相等——此时即使旧快照有弃用信息、新元数据没有，也必须丢弃，最终断言deprecated为undefined。

两条用例一正一反，精确划定了修复的边界：解析未变 → 保留旧弃用标记；解析变化 → 尊重新元数据。

四、Rust 侧的对应实现：pnpm 原生版同样受益

当前仓库同时维护着 pnpm 的 Rust 原生实现（pnpm/crates），该修复同样覆盖了 Rust 侧的依赖解析与锁文件生成流程。

在 pnpm/crates/lockfile/src/package_metadata.rs 中，锁文件的包元数据模型为deprecated字段预留了类型安全的表达方式：

pub deprecated: Option<String>,

采用Option<String>而非直接String，意味着"该字段可能不存在"被显式建模——这与 TypeScript 侧opts.prevSnapshot?.deprecated != null的判断一一对应，只有旧快照中确实存在该字段（Some）时才可能回退恢复。

在 Rust 侧依赖图转锁文件的流程中，相关处理位于 pnpm/crates/package-manager/src/dependencies_graph_to_lockfile/packages.rs，而全流程的其他环节（如build_snapshot.rs、install_with_fresh_lockfile.rs）也贯穿了deprecated字段的透传，说明该元数据从解析到落盘的全链路在 Rust 实现中同样被完整保留。从源码结构看，Rust 侧与 TypeScript 侧遵循相同的设计原则：registry 元数据优先、旧快照兜底、仅限解析未变时恢复。

五、实践指导：如何复现与验证该修复

5.1 最小复现思路

要复现"弃用标记静默丢失"，需要模拟 registry 元数据的不一致返回：

1. 准备一个 registry 镜像（或使用支持自定义响应的小型 mock registry），先返回带deprecated字段的包元数据；
2. 执行一次pnpm install，确认pnpm-lock.yaml中对应条目出现deprecated字段；
3. 修改 mock registry，让同一版本号的元数据不再返回deprecated字段（模拟 CDN 缓存分层、镜像同步延迟等不一致场景）；
4. 再次执行pnpm install；
5. 修复前：锁文件中该条目的deprecated会被删除；
6. 修复后：由于解析结果未变（tarball、integrity 一致），旧锁文件中的弃用标记会被保留。

5.2 验证当前实现是否符合预期

验证分为两个层面：

• 单元层面：直接运行 pnpm11/installing/deps-resolver/test/updateLockfile.test.ts 中的两条用例，pnpm test updateLockfile即可确认"未变保留 / 变化丢弃"两个方向的断言全部通过；
• 端到端层面：在真实项目中制造一次"元数据漂移"（见 5.1），对比修复前后锁文件的 diff，观察deprecated行是否被稳定保留。

5.3 对工程实践的启示

1. 锁文件是元数据的稳定锚点：既然deprecated是 registry 可变的唯一字段，把已记录的弃用信息视为锁文件需要守护的资产，而不是可以被覆盖的临时状态；
2. "解析未变"是复用旧元数据的前提：任何旧快照字段的回退都必须先确认resolution相等，否则会把历史元数据错误地嫁接到新版本上；
3. 关注弃用警告的连续性：pnpm的弃用警告依赖锁文件中的该字段，修复后团队在持续集成与日常安装中都能稳定看到弃用提示，避免安全信号被静默吞掉。

六、结语

这个 changeset 虽然只是一次patch级别的修复，但它触及了包管理器一个容易被忽略的深层问题：当上游元数据不稳定时，本地锁文件应当充当可信的缓存层，而不是被动接受每次 registry 返回的"现状"。通过 updateLockfile.ts 中"新元数据优先、旧快照兜底、resolution 相等才恢复"的三段式逻辑，pnpm 在 TypeScript 与 Rust 双实现中都守住了弃用信息的连续性，让 #13846 所描述的"解析未变、弃用被丢"的静默数据丢失问题得到根治。对于任何依赖 lockfile 驱动安装的工程来说，理解并测试这类元数据合并边界，都是保证供应链可见性的重要一环。

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