企业官网建设流程全解析

pnpm overrides 接管自动安装的 peer 依赖：从 changeset 到 hoistPeers 源码解析

【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm

本篇围绕 changeset overrides-reach-auto-installed-peers.md 展开：overrides现在也能约束 pnpm 在autoInstallPeers开启时自动安装的 peer 依赖。读完后，你将理解这次行为变更要解决"重复副本"问题的机理，能在自己的项目中复现并验证该场景，并掌握从 hoistPeers 源码 到测试用例的完整实现证据链。

背景：pnpm 如何自动安装 peer 依赖

pnpm 的autoInstallPeers（默认开启）会处理一个常见痛点：某依赖声明了peerDependencies，但没有任何项目显式声明它。此时 pnpm 不会把 peer 留空，而是把它作为"缺失的必需 peer"补进依赖图并安装。

这条自动补装路径的核心在依赖解析器中。resolveDependencies.ts 中有一段while (true)循环：每一轮收集各 importer 的missingPeers，交给hoistPeers计算应补装哪些依赖，再递归解析，直到没有新的缺失 peer。关键调用点见该文件第 416-423 行与第 466 行：

const _hoistPeers = hoistPeers.bind(null, { autoInstallPeers: ctx.autoInstallPeers, allPreferredVersions: ctx.allPreferredVersions, workspaceRootDeps, overrideBareSpecifier: ctx.overrideBareSpecifier == null ? undefined : (name, range) => ctx.overrideBareSpecifier!(name, range, options.prefix), })

注意这里的options.prefix（importer 所在目录）被一并传入 override 函数——这为后面"本地file:/link:覆盖目标按声明方目录解析"埋下伏笔。

旧行为的缺口：overrides 只改写"有人声明的依赖"

pnpm 的overrides传统上通过 read-package hook 生效：解析每个包的 manifest 时，把命中的依赖改写（或移除）。但自动安装的 peer没有声明它的 manifest——它是由解析器凭空补装的边，read-package hook 根本没机会触及它。旧版本下这类 peer 只能按其声明方给出的 peer range 去注册表解析。

后果就是 changeset 里描述的场景：你本想用overrides把某个包锁死到唯一版本，结果自动安装的 peer 绕过了锁，按 peer range 又解析出一份旧版本，项目里出现同一包的两个副本。changeset 给出的例子是：

# pnpm-workspace.yaml（或 .npmrc 的 overrides 配置） overrides: react: npm:react@19.2.0

项目只依赖了lucide-react（它声明react为 peer）。旧行为下 pnpm 会为这个没人显式声明的 peer 安装react@18.3.1；变更之后，安装的正是被 override 钉住的react@19.2.0。该变更对应上游 issue #13320。

changeset 的 frontmatter 声明了本次受影响的包及 bump 级别：@pnpm/hooks.read-package-hook与@pnpm/installing.deps-resolver为 minor，@pnpm/installing.deps-installer、pacquet与pnpm为 patch。

新实现：DependencyOverrider 直通 hoistPeers

1. 新的 override 入口：createDependencyOverrider

改动在 read-package-hook 包中新增了独立于 manifest 改写的入口。createVersionsOverrider.ts 定义了函数类型DependencyOverrider及其工厂函数createDependencyOverrider（第 40-55 行），并经 index.ts 导出：

/** * Resolves the specifier an override imposes on a single dependency edge, or * `undefined` when no override claims it. `'-'` means the edge is removed. * * Edges that have no declaring manifest — a peer pnpm auto-installs — reach * the overrides through this function instead of through the read-package * hook, so parent-scoped overrides (`parent>child`) never apply to them. */ export type DependencyOverrider = (name: string, bareSpecifier: string, dir?: string) => string | undefined

源码注释明确了两点语义：

• 返回'-'表示该依赖边被移除；返回undefined表示没有任何 override 声称它。
• 没有声明方 manifest 的边（即 pnpm 自动安装的 peer）走这条新通道，因此父级作用域 override（parent>child形式）天然不适用——parent>child的匹配依赖声明方的name/version（见同文件pickOverridesOfParent，第 131-139 行），而自动安装的 peer 没有声明方。

工厂函数还有一个性能短路：若配置里只有parent>child形式的 override（没有任何能声称"未声明依赖"的项），直接返回undefined，解析器就完全跳过逐 peer 的 override 查询。对于没有 overrides 的普通项目，这是零开销。

2. hoistPeers 中 override 的裁决规则

hoistPeers.ts 的hoistPeers新增overrideBareSpecifier选项（第 24 行），裁决逻辑在第 36-44 行：

const rootBareSpecifier = findWorkspaceRootDep(opts.workspaceRootDeps, peerName)?.normalizedBareSpecifier // An override redirects a hoist; it must never create one, or disabling // autoInstallPeers would still install a peer nobody depends on. const overridden = opts.autoInstallPeers || rootBareSpecifier ? opts.overrideBareSpecifier?.(peerName, range) : undefined if (overridden != null) { if (overridden !== '-') { dependencies[peerName] = overridden } continue }

从源码结构看，这里确立了四条规则：

1. override 只能"改道"，不能"创造"。只有autoInstallPeers开启、或 workspace 根目录自己声明了该包（此时即便关闭 autoInstallPeers 也会发生去重抬升）时，才咨询 override。若两者都不成立，即使配置了 override 也不会为无人依赖的 peer 安装任何副本。
2. override 结果优先于 preferred-versions 去重。命中后直接continue，跳过后面基于allPreferredVersions的版本收敛逻辑——这正是修复"第二份副本"的关键：去重只能收敛到图里已解析的版本（如react@18.3.1），而 override 能把边指向钉住的react@19.2.0。
3. '-'即删除。override 值为'-'时该 peer 不被安装。
4. 未命中 override 时，原有的"workspace 根依赖抬升 → preferred versions 去重 → 按 peer range 解析"链路保持不变。

3. 接线位置：安装主流程与 peer 问题检查

deps-installer 在两处把 override 通道接进解析器：

• 安装主流程 install/index.ts 第 1998 行：overrideBareSpecifier: createDependencyOverrider(opts.parsedOverrides, opts.lockfileDir)。
• peer 依赖问题检查（pnpm peers等命令的分析路径）getPeerDependencyIssues.ts 第 84 行做了同样接线，保证诊断视图与实际安装行为一致。

另外，createVersionsOverrider.ts 的resolveOverriddenBareSpecifier/resolveLocalOverride（第 312-322 行）负责本地覆盖目标的解析：file:/link:形式的 override 若用相对路径声明，会相对"声明该依赖的 importer 目录"（即传入的dir/options.prefix）换算，与该项目显式声明该依赖时的行为完全一致。

行为边界：五个测试用例划定的契约

hoistPeers.test.ts 第 333-394 行集中固化了本次变更的行为契约，五个用例分别对应上述四条规则：

在 deps-installer 的安装集成测试 autoInstallPeers.ts（第 737 行附近）与 validatePeerDependencies.ts 中，也有覆盖 "overrides 与 autoInstallPeers/peer 校验联动" 的安装级用例，可在仓库中进一步查证端到端行为。

实践要点与适用边界

• 适用前提：本变更属于当前仓库pnpm11/下的 TS 实现（对应 changeset 中列出的@pnpm/installing.*与@pnpm/hooks.read-package-hook包）。升级包含此 changeset 的 pnpm 版本后，overrides对自动安装 peer 的约束自动生效，无需额外配置。
• 语义提醒：
  • parent>child形式的 override 不作用于自动安装的 peer（没有声明方 manifest 可匹配），需要钉这类 peer 时使用全局形式的 override（如overrides: { react: npm:react@19.2.0 }）。
  • override 返回'-'会把自动安装的 peer 一并移除；关闭autoInstallPeers且根目录未声明该包时，override 不会"补装"任何东西。
• 验证方式：可用pnpm why react或pnpm ls观察自动安装 peer 的解析结果；行为边界可直接对照 hoistPeers.test.ts 的五个单测，实现细节见 hoistPeers.ts 与 createVersionsOverrider.ts。

【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm