pnpm 版本切换拒绝损坏版本：从 `packageManager` 钉住到 `ERR_PNPM_BROKEN_PNPM_RELEASE` 的完整机制

pnpm 版本切换拒绝损坏版本从packageManager钉住到ERR_PNPM_BROKEN_PNPM_RELEASE的完整机制【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm本指南以 pnpm 仓库的变更记录 refuse-broken-release-on-version-switch.md 为核心结合 TypeScript 版pnpm11与 Rust 版pnpm/crates的源码、错误定义与测试用例系统讲解当项目通过packageManager或devEngines.packageManager将 pnpm 钉在一个损坏的版本上时新版 pnpm 如何在版本切换环节提前拒绝、如何给出可执行的修复指引以及为什么已在运行的损坏版本不会被拒绝。读完你将掌握该错误码的含义、触发条件、hint 文案背后的设计取舍并能依据源码定位到对应的检查函数与测试。一、这条变更记录讲的是什么关联文档一个 changeset 文件的原文非常凝练A project pinned to a broken pnpm release viapackageManagerordevEngines.packageManagernow reports which release is broken and what to do about it, instead of failing inside the installer.pnpm self-updatealready refused these releases; the version switch does too.拆解这句话可以提炼出三个核心事实触发入口有两个项目的packageManager字段package.json中的packageManager: pnpmx.y.z与devEngines.packageManagerdevEngines字段中的包管理器钉住声明行为变化在此之前切到损坏版本会在安装器内部失败failing inside the installer——即已经下载、解压、安装到一半才报错用户只看到一个底层安装错误现在则在切换动作发生之前就明确报告哪个版本损坏、该怎么办对称性pnpm self-update早已拒绝这些版本拒绝逻辑由 installPnpm.ts 中的assertReleaseIsInstallable提供本变更把同一道防线延伸到了版本切换version switch路径。从源码看这一变更同时在两条代码线上落地TypeScript 版 CLI 的 switchCliVersion.ts 与 Rust 版 CLI 的 execute.rs两侧共享完全一致的错误码与提示语义。二、什么是损坏版本BROKEN_RELEASES的判定依据损坏不是一个形容词而是一份明确的版本黑名单。在 TS 版中定义位于 installPnpm.ts/** * Versions whose pnpm/exe shipped platform packages with no binary, so it * cannot run. Keyed by version, not package: the pin is shared but the wrapper * is not, so a developer on the JS pnpm — which does run at these versions — * would otherwise pin one and break every teammate on pnpm/exe. */ const BROKEN_RELEASES: ReadonlySetstring new Set([11.12.0, 11.13.0]) /** * Whether version can be installed at all — false for the * {link BROKEN_RELEASES}. For callers that pick a version rather than being * handed one, and so can choose another instead of failing. */ export function isReleaseInstallable (version: string): boolean { return !BROKEN_RELEASES.has(version) }Rust 版的对应实现位于 install_pnpm.rs用matches!表达同一份名单pub(crate) fn is_release_installable(version: str) - bool { !matches!(version, 11.12.0 | 11.13.0) }2.1 判定以版本为单位而非包名注释中的一句值得展开the pin is shared but the wrapper is not钉住是共享的但包装器不是。pnpm/exe是携带平台原生二进制的 pnpm 分发形式SEA 单文件可执行而pnpmJS 版是另一套包装器。在11.12.0、11.13.0这两个版本上pnpm/exe发布的平台包没有附带可执行二进制因此通过pnpm/exe安装后无法运行。关键设计在于黑名单以版本号为准而不是以包名为准。因为packageManager/devEngines.packageManager的钉住是项目级共享的——一个项目钉住pnpm11.12.0团队里使用 JS 版pnpm的成员可能恰好能跑起来但使用pnpm/exe的成员会在安装后无法运行。如果黑名单只拦pnpm/exe这一个包名就会产生同项目、同 pin、不同结局的割裂体验。按版本拦截则无论走哪个包装器都会被统一拒绝。2.2 两个入口的语义差异packageManager: pnpm11.12.0直接声明本项目使用 pnpm 的哪个版本devEngines.packageManager: { name: pnpm, version: 11.12.0, onFail: download }由devEngines协议描述包管理器约束onFail: download表示不满足时自动下载目标版本见 switchCliVersion.test.ts 中测试构造的wantedPackageManager。两条入口最终都会汇入同一个期望版本wanted version解析流程因此本变更同时覆盖了它们。三、拒绝时的错误报告错误码、文案与 hint拒绝不是抛出含糊的内部错误而是带PnpmError错误码与可操作 hint 的明确诊断。TS 版核心函数在 installPnpm.ts/** Throws when version is one of the {link BROKEN_RELEASES}. */ export function assertReleaseIsInstallable (version: string): void { if (isReleaseInstallable(version)) return throw new PnpmError( BROKEN_PNPM_RELEASE, pnpm v${version} is a broken release and cannot be installed, { hint: Its pnpm/exe build shipped without a binary and does not run. Even where it does run, pinning it would break everyone on the project who uses pnpm/exe, because the pin is shared. Choose another version, or run pnpm self-update latest., } ) }Rust 版的错误定义在 self_update.rs#[display(pnpm v{version} is a broken release and cannot be installed)] #[diagnostic( code(ERR_PNPM_BROKEN_PNPM_RELEASE), help( r#Its pnpm/exe build shipped without a binary and does not run. Even where it does run, pinning it would break everyone on the project who uses pnpm/exe, because the pin is shared. Choose another version, or run pnpm self-update latest.# ) )] BrokenPnpmRelease { version: String },3.1 错误信息的三层结构组成内容作用错误码ERR_PNPM_BROKEN_PNPM_RELEASETS 侧PnpmError的 codeRust 侧diagnostic的 code供 CI、脚本与工具链稳定匹配不必解析文案主消息pnpm v11.12.0 is a broken release and cannot be installed明确指出哪一个版本损坏满足 changeset 中 reports which release is broken 的要求hintpnpm/exe构建缺少二进制、共享 pin 会波及队友、可选操作满足 what to do about it给出两条出路hint 中给出的两条出路正好对应两个修复方向换一个可用的版本重新钉住项目中的packageManager/devEngines.packageManager到非黑名单版本如11.13.1、12.0.0等pnpm self-update latest把你本机的 pnpm 更新到最新发布版本摆脱损坏版本。注意ERR_PNPM_BROKEN_PNPM_RELEASE与 self_update.rs 中的ERR_PNPM_BROKEN_PNPM_INSTALL是两个不同的错误码后者描述安装完成后发现装好的版本无法运行安装器内部失败的后置防线前者描述安装之前就判定该版本不可安装。本变更让版本切换路径不再走到后者那种装完才发现的局面。四、版本切换中的检查位置switchCliVersion的调用链拒绝动作发生在版本切换流程的哪个节点决定了它能否真正避免在安装器内部失败。看 switchCliVersion.ts 的完整流程解析期望版本 wantedVersion来自 packageManager / devEngines │ ▼ 读取 env lockfilepnpm-lock.yaml 中已记录的解析结果 │ ▼ 需要时从 registry 解析确切的版本号resolvePackageManagerIntegrities │ ▼ ★ 若解析出的版本 当前正在运行的版本 → 直接返回不拒绝 │ ▼ ★ assertReleaseIsInstallable(pmVersion) ← 本变更的核心检查点 │ ▼ 通过 → assertPackageManagerLockfileUsesRegistryResolutions校验 lockfile 解析形态 │ ▼ installPnpmToStore → 用 spawn.sync 启动新版本的 pnpm转发全部参数对应代码位于 switchCliVersion.ts// If the wanted version matches the current version, no switch needed. // Skip install-to-store entirely — were already running this version. if (pmVersion packageManager.version) { await storeToUse?.ctrl.close() return } // Deliberately after the check above: switching to a broken release is // refused, but running one already installed is not. Someone whose pnpm is a // broken release still needs it to work well enough to move off it. try { assertReleaseIsInstallable(pmVersion) } catch (err: unknown) { await storeToUse?.ctrl.close() throw err }4.1 检查点的精确位置可以看到检查被刻意放在了**与当前版本相同则提前返回之后**、安装到 store / spawn 子进程之前。这个顺序是有意为之的位于安装之前 → 损坏版本永远不会被下载和安装不会出现装到一半炸掉或装完才发现跑不了的中间态位于相同版本提前返回之后 → 见下一节的设计取舍。Rust 版在 execute.rs 的install_switch_target中同样在进入安装前调用assert_release_is_installable(version)?且先判断version PNPM_VERSION再检查与 TS 版顺序完全一致。4.2 为什么正在运行的损坏版本不拒绝这是本变更最容易引起疑问的设计点注释解释得很清楚Someone whose pnpm is a broken release still needs it to work well enough to move off it.如果某位开发者的 pnpm已经是11.12.0这个损坏版本例如在版本发布当天通过其他途径装上或团队此前已钉住而项目又恰好钉住这个版本——此时版本切换的目标版本就等于正在运行的版本switchCliVersion会直接返回而不触发检查。原因这台机器上的 pnpm确实能跑否则用户根本无法执行命令它处于能运行的状态虽然属于损坏发布的分发缺陷但当前实例可用如果在这里拒绝用户将陷入死锁项目钉住损坏版本 → 版本切换拒绝 → 用户永远无法用 pnpm 执行任何命令来修改package.json或升级自己。也就是说切换需要下载安装新副本时拒绝损坏版本保持现状已安装且正在运行时不拒绝。这是fail loudly与dont strand the user之间的平衡。对应的测试用例精确锁定了这一语义见 switchCliVersion.test.ts// The refusal must not strand anyone: a developer whose pnpm *is* a broken // release still needs it to run, or they have nothing to move off it with. test(does not refuse a broken release that is already the running version, async () { mockPackageManager.version 11.12.0 // ... wantedPackageManager 钉住 11.12.0 ... await expect(switchCliVersion(config, context)).resolves.toBeUndefined() expect(installPnpmToStore).not.toHaveBeenCalled() })五、测试如何锁住这个行为仓库为这条变更配备了双端TS 与 Rust测试可以从测试断言反推行为规格。5.1 TS 版拒绝、放行与不困住用户switchCliVersion.test.ts 的核心用例test(refuses to switch to a broken release instead of failing inside the installer, async () { const context { rootProjectManifestDir: /project, wantedPackageManager: { name: pnpm, version: 11.12.0, fromDevEngines: true, onFail: download }, } as unknown as ConfigContext readEnvLockfile.mockResolvedValue(envLockfileFor(11.12.0)) const exit jest.spyOn(process, exit).mockImplementation((() undefined) as never) try { await expect(switchCliVersion(config, context)).rejects.toThrow(/11\.12\.0 is a broken release/) } finally { exit.mockRestore() } expect(installPnpmToStore).not.toHaveBeenCalled() })注意两个断言点rejects.toThrow(/11\.12\.0 is a broken release/)—— 断言拒绝且明确点名了损坏版本号这正是 changeset 中 reports which release is broken 的测试落点expect(installPnpmToStore).not.toHaveBeenCalled()—— 断言安装器从未被调用验证不是失败在安装器内部而是在安装之前就拒绝。配套用例还覆盖了反向行为switchCliVersion.test.ts切换到非损坏版本11.13.1时正常走完installPnpmToStore与spawnSync全流程证明该检查不会误伤正常版本。5.2selfUpdate侧与错误码的专项测试版本切换复用的assertReleaseIsInstallable本身在 self-update 的测试中也有完整覆盖selfUpdate.test.tstest.each([11.12.0, 11.13.0])逐一验证黑名单版本全部抛出/pnpm v. is a broken release and cannot be installed/专门断言错误码为ERR_PNPM_BROKEN_PNPM_RELEASE且 hint 包含 pin is shared共享钉住的团队影响语义反向用例验证11.11.0、11.13.1、12.0.0等版本允许安装。5.3 Rust 版测试pnpm/crates/cli/src/cli_args/self_update/install_pnpm/tests.rs 中fn assert_release_is_installable_refuses_the_broken_releases() { // ... let err assert_release_is_installable(version).unwrap_err(); assert!(err.to_string().contains(broken release), {err}); }以及assert_release_is_installable_allows_every_other_release允许其余所有版本与 TS 版测试构成一一对应的双端规格。六、同族防线pnpm init与self-update中的一致策略值得说明的是这一拒绝损坏版本的策略并非孤例而是贯穿 pnpm 的多个选版本入口。理解这些同族防线有助于把本变更放进整体设计语境入口文件策略版本切换本变更switchCliVersion.ts / execute.rs切换到黑名单版本 → 拒绝self-updateself_update.rs更新到黑名单版本 → 拒绝早于本变更已有pnpm init钉住最新版init.ts解析latest得到黑名单版本时不把它写进新项目的packageManager钉住回退到当前版本init.ts 中的注释与本文主题一脉相承A broken release is refused for the reason the pin exists at all: it is shared, so pinning one the running wrapper happens to survive would still break every teammate on the other wrapper.即钉住是共享的shared pin这一事实是拒绝损坏版本策略跨所有入口统一的根本原因——你个人也许侥幸能跑但你的整个团队都会因为同一个packageManager声明而受损。七、实战遇到ERR_PNPM_BROKEN_PNPM_RELEASE该怎么办当你在项目根目录执行任意 pnpm 命令报错形如ERR_PNPM_BROKEN_PNPM_RELEASE pnpm v11.12.0 is a broken release and cannot be installed Its pnpm/exe build shipped without a binary and does not run. Even where it does run, pinning it would break everyone on the project who uses pnpm/exe, because the pin is shared. Choose another version, or run pnpm self-update latest.按如下顺序处置查看钉住声明检查根目录package.json中的packageManager字段如packageManager: pnpm11.12.0以及devEngines.packageManager块升级钉住的版本将版本改为黑名单之外的可用版本测试确认的可用版本包括11.11.0、11.13.1、12.0.0例如改为packageManager: pnpm11.13.1后重新运行命令触发切换或升级本机 pnpm执行pnpm self-update latest将本机 CLI 提升到最新发布版该命令自带拒绝降级与拒绝损坏版本的策略参见 SelfUpdateArgs 中 Defaults to thelatestdist-tag (which refuses to downgrade) 的说明如果你当前运行的恰好就是损坏版本不会触发该错误见 4.2 节请直接执行pnpm self-update latest离开它。八、小结本变更以极小的代码面一份黑名单 一个断言函数完成了行为契约的升级版本切换路径从装到一半失败变为装之前就拒绝并给出指引。其设计要点可归纳为三条提前失败fail early检查点位于安装之前损坏版本永远不会进入下载与安装流程这是对instead of failing inside the installer的直接实现按版本而非按包名判定因为packageManager钉住是项目级共享的pnpm/exe与 JSpnpm两个包装器必须行为一致拒绝不困住用户正在运行的损坏版本不受影响保证用户始终有工具去完成自我修复。该行为由 TSswitchCliVersion.test.ts / selfUpdate.test.ts与 Rusttests.rs两侧测试共同锁定错误码ERR_PNPM_BROKEN_PNPM_RELEASE在 installPnpm.ts 与 self_update.rs 中定义一致——无论你使用的是 TS 版还是 Rust 版 pnpm行为契约完全相同。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考