pnpm 依赖环下的全局虚拟存储哈希修复build-required逆向闭包原理与源码剖析【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm导读本篇文章围绕 pnpm 仓库中一份 changeset.changeset/fix-cyclic-build-hashes.md记录的缺陷修复展开深入讲解 pnpm 与 pacquet 在计算全局虚拟存储Global Virtual StoreGVS目录哈希时如何处理依赖环dependency cycle这一图论边界场景。读完本文你将理解 GVS 槽位路径的哈希组成、allow-build策略如何决定 engine 片段是否进入哈希以及为何必须用全图逆向闭包而非逐节点遍历来保证环内节点哈希与遍历顺序无关。文章同时给出 TypeScript 与 Rust 双栈的源码级实现对照与测试验证。修复背景GVS 哈希、构建脚本与依赖环的交汇点pnpm 使用全局虚拟存储store/links/来去重共享依赖每个包在虚拟存储中占据一个槽位slot槽位路径由三部分组成globalVirtualStoreDir/name/version/hash其中hash片段是哈希摘要hex digest它在 pnpm11 的实现中由calcGraphNodeHash计算见 pnpm11/deps/graph-hasher/src/index.ts核心载荷为hashObjectWithoutSorting({ engine, deps }, { encoding: hex })即{ engine, deps }两个字段——engine是运行脚本所用的 Node/运行时标识形如platform-arch-nodemajordeps是递归依赖图哈希。为了让纯 JS 包在 Node 升级或架构迁移后仍然复用同一个 GVS 目录pnpm 引入了engine 门控gating只有自己会跑构建脚本、或传递依赖某个会跑构建脚本的包的节点才把 engine 字符串纳入哈希global_virtual_store_path.rs。这份 changeset 修复的正是这个门控集合在存在依赖环时的计算缺陷Fixed global virtual store hashes for dependency cycles. Every package that transitively depends on an allowed build now includes the engine in its store path, independent of traversal order.一句话凡传递依赖了允许构建allowed build包的节点其 store path 必须包含 engine且结果不得依赖遍历顺序。旧实现的问题逐节点遍历在环上产生非确定性结果calcGraphNodeHash的注释直接点明了缺陷的根源// When buildRequiredDepPaths is provided (derived from the allowBuilds // config), we only include the engine name for packages that are allowed // to build or transitively depend on a package that is allowed to build. const includeEngine buildRequiredDepPaths undefined || buildRequiredDepPaths.has(depPath)Rust 侧同样如此global_virtual_store_path.rslet include_engine build_required_dep_paths.is_none_or(|set| set.contains(dep_path));问题在于如果buildRequiredDepPathsengine 门控集合是在逐个节点、按依赖方向递归的过程中就地扩张的那么对于环a → b → a从a出发遍历与从b出发遍历可能得到不同的门控结论进而得到不同的哈希摘要——同一个包在两次安装中落到不同的 GVS 目录破坏缓存复用甚至导致重复解压。修复方案全图逆向闭包一次性计算门控集合修复的核心是改变门控集合的生成方式不再与节点哈希计算耦合而是先在整张依赖图上做一次逆向闭包reverse closure得到与遍历顺序无关的固定集合。TypeScript 侧computeBuildRequiredDepPaths在 pnpm11/deps/graph-hasher/src/index.ts 中先用computeBuiltDepPaths依据allowBuild策略筛选出直接允许构建的 depPath 集合index.ts构建一张parentsByChild的反向邻接表child → 所有 parent以直接允许构建的节点为种子做 BFS/DFS 式逆向传播凡是直接或间接依赖了构建节点的祖先节点全部加入buildRequiredDepPaths。关键注释点明了环上确定性这一设计目标// It is computed as one graph-wide reverse closure, // so a package inside a dependency cycle gets the same answer no matter // which node the hasher reaches it from.由于反向邻接表覆盖全图、闭合过程只做集合扩张if (!buildRequiredDepPaths.has(parent))保证不会重复入队环上的每个节点只要存在一条通向构建节点的路径就一定会被收录无论哈希器从环的哪个节点进入得到的都是同一个全集。这正是 changeset 中 independent of traversal order 的工程含义。Rust 侧build_required_dep_pathsRust 栈在 pnpm/crates/graph-hasher/src/dep_state.rs 提供了等价实现由index_parents_by_child反向索引与集合扩张循环组成deps-restorercrate 中的engine_gating_dep_paths负责把AllowBuildPolicy的判定结果转换成种子集合再调用pnpm_graph_hasher::build_required_dep_paths完成闭包pnpm/crates/deps-restorer/src/virtual_store_layout/graph_hash.rs。GVS 哈希器GvsHasher在构造时一次性计算门控集合并复用到整个 lockfile 的所有快照let build_required_dep_paths allow_build_policy.map(|policy| engine_gating_dep_paths(policy, snapshots, graph));None与空集语义不同None表示关闭门控、所有节点都带 engine空集表示任何节点都不带 engineglobal_virtual_store_path.rs 及 graph_hash.rs。此外GvsHasher::fingerprint会把门控集合排序后写进缓存指纹保证布局缓存不被HashMap迭代顺序扰动graph_hash.rs。测试验证环成员必须一致地包含 engine两个测试文件从不同层面锁定了修复行为TypeScript环成员与顺序无关性pnpm11/deps/graph-hasher/test/allowBuildIdentity.test.ts 构造了如下场景a → b、b → a构成依赖环a还依赖builder允许构建pure-js是无关的纯 JS 叶子。测试分别以正序[a, b, builder, pure-js]和逆序[b, a, ...]两种pkgMeta顺序跑两遍断言expect(node20.get(a)).not.toBe(node22.get(a)) // a 必须含 engine expect(node20.get(b)).not.toBe(node22.get(b)) // b 作为环成员同样必须含 engine expect(node20.get(pureJs)).toBe(node22.get(pureJs)) // 纯 JS 叶子与 engine 无关即a、b两个环成员在 Node 20 / Node 22 下哈希不同说明 engine 进入了它们的哈希而pure-js的哈希跨 Node 版本保持一致——同时验证了环内节点包含 engine与纯 JS 包保持 engine 无关两个目标且结论不受遍历顺序影响。同文件第一个测试allowBuildIdentity.test.ts还验证了allowBuild回调按 depPath 逐一被咨询的门控入口行为。Rust逆向闭包跨越环pnpm/crates/graph-hasher/src/dep_state/tests.rs 的build_required_dep_paths_reaches_every_parent_across_a_cycle直接断言给定一个含环的图与种子集合{builder}闭包结果必须包含环上所有能到达 builder 的祖先build_required_dep_paths_handles_empty_and_missing_builders则覆盖了空集与构建节点不在图中的边界情况dep_state.rs对应 TypeScript 侧built set 来自 allowBuild 策略而非图二者可能不一致的注释index.ts。深入理解engine 门控之外哈希还有哪些组成部分理解本次修复还需要把calcGraphNodeHash的完整输入链路看清楚index.ts输入来源作用depscalcDepGraphHash递归计算基于fullPkgIdpkgIdWithPatchHash:integrity与 children 子树任一子依赖的内容或版本变化都会改变父槽位路径engine快照自身的engines.runtimepinreadSnapshotRuntimePin优先否则取 install-widenodeVersion由engineName格式化只有门控集合中的节点才携带project仅当 resolution 为directory本地目录依赖时取lockfileDir让每个项目在 GVS 中拥有独立槽位避免file:目录依赖跨项目串用值得注意的细节环对递归哈希本身是安全的calcDepGraphHash通过parents集合切断环避免无限递归index.tsRust 侧同样用parents集合实现dep_state.rs。本次修复只针对 engine 门控集合不改变依赖图哈希的递归逻辑。目录依赖与版本段目录快照在 lockfile 中不记录版本哈希器以固定段directory占位index.ts测试覆盖了该段在解析器已知版本与lockfile 未知版本两种场景下保持一致calcGraphNodeHash.test.ts。路径安全性所有 GVS 槽位路径都经formatGlobalVirtualStorePath汇聚assertNoPathTraversal会在版本段包含..时抛出ERR_PNPM_INVALID_DEPENDENCY_NAME防止槽位路径逃逸出 store 根目录index.ts。变更影响与适用范围该 changeset 标注了三个受影响包pnpm/deps.graph-hasherTypeScript 哈希库、pnpm本体、以及 Rust 栈对应的pacquet。这意味着pnpmTypeScript CLI安装时对 lockfile 每个快照计算 GVS 槽位门控集合改为全图逆向闭包后含依赖环的项目在pnpm install时环内所有传递依赖构建包的节点都能稳定地获得包含 engine 的存储路径。pacquetRust 实现graph-hashercrate 的build_required_dep_paths与calc_graph_node_hash与 TS 侧保持行为一致deps-restorer的GvsHasher将其用于冻结安装frozen-lockfile与快照规划阶段的槽位计算。已知边界Rust 侧create_full_pkg_id尚未支持variations跨平台变体resolution——注释明确指出 pacquet 的 lockfile 模型还没有该类型待引入时需补充selectPlatformVariant分支graph_hash.rs。小结本次修复的精髓可以概括为一句话engine 门控集合必须是一次性的全图逆向闭包而不是随哈希遍历过程累积的产物。它从数据结构层面根除了依赖环上的遍历顺序敏感性问题使纯 JS 包跨 Node 版本复用 GVS 目录与构建相关包稳定包含 engine两个目标在环存在时也能同时成立。如果希望进一步验证可以阅读两份核心测试allowBuildIdentity.test.ts 与 dep_state/tests.rs它们在双栈上锁定了相同的行为契约。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pnpm 依赖环下的全局虚拟存储哈希修复：`build-required` 逆向闭包原理与源码剖析
pnpm 依赖环下的全局虚拟存储哈希修复build-required逆向闭包原理与源码剖析【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm导读本篇文章围绕 pnpm 仓库中一份 changeset.changeset/fix-cyclic-build-hashes.md记录的缺陷修复展开深入讲解 pnpm 与 pacquet 在计算全局虚拟存储Global Virtual StoreGVS目录哈希时如何处理依赖环dependency cycle这一图论边界场景。读完本文你将理解 GVS 槽位路径的哈希组成、allow-build策略如何决定 engine 片段是否进入哈希以及为何必须用全图逆向闭包而非逐节点遍历来保证环内节点哈希与遍历顺序无关。文章同时给出 TypeScript 与 Rust 双栈的源码级实现对照与测试验证。修复背景GVS 哈希、构建脚本与依赖环的交汇点pnpm 使用全局虚拟存储store/links/来去重共享依赖每个包在虚拟存储中占据一个槽位slot槽位路径由三部分组成globalVirtualStoreDir/name/version/hash其中hash片段是哈希摘要hex digest它在 pnpm11 的实现中由calcGraphNodeHash计算见 pnpm11/deps/graph-hasher/src/index.ts核心载荷为hashObjectWithoutSorting({ engine, deps }, { encoding: hex })即{ engine, deps }两个字段——engine是运行脚本所用的 Node/运行时标识形如platform-arch-nodemajordeps是递归依赖图哈希。为了让纯 JS 包在 Node 升级或架构迁移后仍然复用同一个 GVS 目录pnpm 引入了engine 门控gating只有自己会跑构建脚本、或传递依赖某个会跑构建脚本的包的节点才把 engine 字符串纳入哈希global_virtual_store_path.rs。这份 changeset 修复的正是这个门控集合在存在依赖环时的计算缺陷Fixed global virtual store hashes for dependency cycles. Every package that transitively depends on an allowed build now includes the engine in its store path, independent of traversal order.一句话凡传递依赖了允许构建allowed build包的节点其 store path 必须包含 engine且结果不得依赖遍历顺序。旧实现的问题逐节点遍历在环上产生非确定性结果calcGraphNodeHash的注释直接点明了缺陷的根源// When buildRequiredDepPaths is provided (derived from the allowBuilds // config), we only include the engine name for packages that are allowed // to build or transitively depend on a package that is allowed to build. const includeEngine buildRequiredDepPaths undefined || buildRequiredDepPaths.has(depPath)Rust 侧同样如此global_virtual_store_path.rslet include_engine build_required_dep_paths.is_none_or(|set| set.contains(dep_path));问题在于如果buildRequiredDepPathsengine 门控集合是在逐个节点、按依赖方向递归的过程中就地扩张的那么对于环a → b → a从a出发遍历与从b出发遍历可能得到不同的门控结论进而得到不同的哈希摘要——同一个包在两次安装中落到不同的 GVS 目录破坏缓存复用甚至导致重复解压。修复方案全图逆向闭包一次性计算门控集合修复的核心是改变门控集合的生成方式不再与节点哈希计算耦合而是先在整张依赖图上做一次逆向闭包reverse closure得到与遍历顺序无关的固定集合。TypeScript 侧computeBuildRequiredDepPaths在 pnpm11/deps/graph-hasher/src/index.ts 中先用computeBuiltDepPaths依据allowBuild策略筛选出直接允许构建的 depPath 集合index.ts构建一张parentsByChild的反向邻接表child → 所有 parent以直接允许构建的节点为种子做 BFS/DFS 式逆向传播凡是直接或间接依赖了构建节点的祖先节点全部加入buildRequiredDepPaths。关键注释点明了环上确定性这一设计目标// It is computed as one graph-wide reverse closure, // so a package inside a dependency cycle gets the same answer no matter // which node the hasher reaches it from.由于反向邻接表覆盖全图、闭合过程只做集合扩张if (!buildRequiredDepPaths.has(parent))保证不会重复入队环上的每个节点只要存在一条通向构建节点的路径就一定会被收录无论哈希器从环的哪个节点进入得到的都是同一个全集。这正是 changeset 中 independent of traversal order 的工程含义。Rust 侧build_required_dep_pathsRust 栈在 pnpm/crates/graph-hasher/src/dep_state.rs 提供了等价实现由index_parents_by_child反向索引与集合扩张循环组成deps-restorercrate 中的engine_gating_dep_paths负责把AllowBuildPolicy的判定结果转换成种子集合再调用pnpm_graph_hasher::build_required_dep_paths完成闭包pnpm/crates/deps-restorer/src/virtual_store_layout/graph_hash.rs。GVS 哈希器GvsHasher在构造时一次性计算门控集合并复用到整个 lockfile 的所有快照let build_required_dep_paths allow_build_policy.map(|policy| engine_gating_dep_paths(policy, snapshots, graph));None与空集语义不同None表示关闭门控、所有节点都带 engine空集表示任何节点都不带 engineglobal_virtual_store_path.rs 及 graph_hash.rs。此外GvsHasher::fingerprint会把门控集合排序后写进缓存指纹保证布局缓存不被HashMap迭代顺序扰动graph_hash.rs。测试验证环成员必须一致地包含 engine两个测试文件从不同层面锁定了修复行为TypeScript环成员与顺序无关性pnpm11/deps/graph-hasher/test/allowBuildIdentity.test.ts 构造了如下场景a → b、b → a构成依赖环a还依赖builder允许构建pure-js是无关的纯 JS 叶子。测试分别以正序[a, b, builder, pure-js]和逆序[b, a, ...]两种pkgMeta顺序跑两遍断言expect(node20.get(a)).not.toBe(node22.get(a)) // a 必须含 engine expect(node20.get(b)).not.toBe(node22.get(b)) // b 作为环成员同样必须含 engine expect(node20.get(pureJs)).toBe(node22.get(pureJs)) // 纯 JS 叶子与 engine 无关即a、b两个环成员在 Node 20 / Node 22 下哈希不同说明 engine 进入了它们的哈希而pure-js的哈希跨 Node 版本保持一致——同时验证了环内节点包含 engine与纯 JS 包保持 engine 无关两个目标且结论不受遍历顺序影响。同文件第一个测试allowBuildIdentity.test.ts还验证了allowBuild回调按 depPath 逐一被咨询的门控入口行为。Rust逆向闭包跨越环pnpm/crates/graph-hasher/src/dep_state/tests.rs 的build_required_dep_paths_reaches_every_parent_across_a_cycle直接断言给定一个含环的图与种子集合{builder}闭包结果必须包含环上所有能到达 builder 的祖先build_required_dep_paths_handles_empty_and_missing_builders则覆盖了空集与构建节点不在图中的边界情况dep_state.rs对应 TypeScript 侧built set 来自 allowBuild 策略而非图二者可能不一致的注释index.ts。深入理解engine 门控之外哈希还有哪些组成部分理解本次修复还需要把calcGraphNodeHash的完整输入链路看清楚index.ts输入来源作用depscalcDepGraphHash递归计算基于fullPkgIdpkgIdWithPatchHash:integrity与 children 子树任一子依赖的内容或版本变化都会改变父槽位路径engine快照自身的engines.runtimepinreadSnapshotRuntimePin优先否则取 install-widenodeVersion由engineName格式化只有门控集合中的节点才携带project仅当 resolution 为directory本地目录依赖时取lockfileDir让每个项目在 GVS 中拥有独立槽位避免file:目录依赖跨项目串用值得注意的细节环对递归哈希本身是安全的calcDepGraphHash通过parents集合切断环避免无限递归index.tsRust 侧同样用parents集合实现dep_state.rs。本次修复只针对 engine 门控集合不改变依赖图哈希的递归逻辑。目录依赖与版本段目录快照在 lockfile 中不记录版本哈希器以固定段directory占位index.ts测试覆盖了该段在解析器已知版本与lockfile 未知版本两种场景下保持一致calcGraphNodeHash.test.ts。路径安全性所有 GVS 槽位路径都经formatGlobalVirtualStorePath汇聚assertNoPathTraversal会在版本段包含..时抛出ERR_PNPM_INVALID_DEPENDENCY_NAME防止槽位路径逃逸出 store 根目录index.ts。变更影响与适用范围该 changeset 标注了三个受影响包pnpm/deps.graph-hasherTypeScript 哈希库、pnpm本体、以及 Rust 栈对应的pacquet。这意味着pnpmTypeScript CLI安装时对 lockfile 每个快照计算 GVS 槽位门控集合改为全图逆向闭包后含依赖环的项目在pnpm install时环内所有传递依赖构建包的节点都能稳定地获得包含 engine 的存储路径。pacquetRust 实现graph-hashercrate 的build_required_dep_paths与calc_graph_node_hash与 TS 侧保持行为一致deps-restorer的GvsHasher将其用于冻结安装frozen-lockfile与快照规划阶段的槽位计算。已知边界Rust 侧create_full_pkg_id尚未支持variations跨平台变体resolution——注释明确指出 pacquet 的 lockfile 模型还没有该类型待引入时需补充selectPlatformVariant分支graph_hash.rs。小结本次修复的精髓可以概括为一句话engine 门控集合必须是一次性的全图逆向闭包而不是随哈希遍历过程累积的产物。它从数据结构层面根除了依赖环上的遍历顺序敏感性问题使纯 JS 包跨 Node 版本复用 GVS 目录与构建相关包稳定包含 engine两个目标在环存在时也能同时成立。如果希望进一步验证可以阅读两份核心测试allowBuildIdentity.test.ts 与 dep_state/tests.rs它们在双栈上锁定了相同的行为契约。【免费下载链接】pnpmFast, disk space efficient package manager项目地址: https://gitcode.com/gh_mirrors/pn/pnpm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
