包管理器开发工具CLI【免费下载链接】pnpmFast, disk space efficient package manager项目地址https://gitcode.com/gh_mirrors/pn/pnpm点击查看免费下载本文基于仓库中 .changeset/safe-pnpr-project-transforms.md 这一变更集changeset展开。该变更集宣告了一项影响pnpm、pnpm/pnpr、pnpm/pnpr.client、pnpm/installing.deps-installer与pacquet的关键改动把patchedDependencies的 SHA-256 哈希与packageExtensions转发给 pnpr 服务端使基于 pnpr 的服务端解析能够在生成的 lockfile 与安装产物中完整保留补丁patches和包扩展package extensions。本文将结合仓库中的客户端实现、服务端协议与测试用例剖析这条数据链路从客户端收集、线上传输、服务端应用到一致性校验的完整闭环。一、背景pnpr 服务端解析为何需要项目变换信息pnpm 在 pnpm11/pnpm/src 与 Rust 实现的 pnpr 服务端pnpr/crates/pnpr之间划分了解析职责当配置了 pnpr 服务器时客户端通过POST /-/pnpr/v0/resolve接口把项目清单、依赖声明与既有 lockfile 发送给服务端由服务端完成依赖图解析并返回新的 lockfile。然而patchedDependencies对特定包应用本地补丁与packageExtensions改写第三方包 manifest注入额外依赖或 peer 依赖都属于会改变解析结果的项目变换——它们会影响哪些依赖被拉入解析图、以及 lockfile 中快照键的形态。补丁文件位于客户端本地服务端无法也不应当读取包扩展来自用户配置同样只存在于客户端。若这两类信息不随请求转发服务端解析出的 lockfile 就会丢失补丁记录与扩展后的依赖关系导致安装产物与本地解析行为不一致。这正是该变更集要解决的问题。二、变更集内容解读一次跨五个包的协同 patch.changeset/safe-pnpr-project-transforms.md 全文很短其技术含量集中在两个部分版本声明front matter五个包同时打上patch级别版本号包变更级别pnpm/installing.deps-installerpatchpnpm/pnpr.clientpatchpnpm/pnprpatchpnpmpatchpacquetpatch五个包横跨客户端pnpm、pacquet、安装协调器pnpm/installing.deps-installer、pnpr 客户端库pnpm/pnpr.client与 pnpr 服务端pnpm/pnpr说明该改动是一条完整的数据通路而非单一模块的局部修补。变更描述summaryForwardpatchedDependencieshashes andpackageExtensionsto pnpr so server-side resolution preserves patches and package extensions in the lockfile and installed packages.两个关键词值得注意patchedDependencieshashes转发的不是补丁文件本身而是每个补丁的哈希值——补丁文件始终留在客户端preserves ... in the lockfile and installed packages目标是让服务端解析出的 lockfile、以及据此安装的产物与本地解析时一样保留补丁与包扩展。三、客户端侧如何收集并转发变换信息客户端的数据收集与请求组装集中在 pnpr/client/src/resolveViaPnprServer.ts 的resolveViaPnprServer函数中。3.1 选项接口两类变换信息如何建模ResolveViaPnprServerOptions接口为该变更新增了两个字段resolveViaPnprServer.ts#L60-L65/** Patch selectors mapped to SHA-256 hashes; patch files stay client-side. */ patchedDependencies?: Recordstring, string /** Manifest extensions applied during server-side resolution. */ packageExtensions?: Recordstring, PackageExtensionpatchedDependencies是一个选择器 → SHA-256 哈希的映射例如{ foo1.0.0: sha256hex… }。注释明确说明补丁文件保留在客户端patch files stay client-sidepackageExtensions是包选择器 → 扩展后 manifest 字段的映射类型为Recordstring, PackageExtension例如为某个包追加peerDependencies或optionalDependencies与之配套的还有allowUnusedPatches?: booleanresolveViaPnprServer.ts#L65允许配置的补丁匹配不到任何已解析包时也不报错。3.2 请求体哪些字段随请求上行组装请求体时resolveViaPnprServer.ts#L170-L200变换信息与其他解析配置一并打包const requestBody JSON.stringify({ projects, registry: opts.registry, registries: opts.registries, overrides: opts.overrides, patchedDependencies: opts.patchedDependencies, packageExtensions: opts.packageExtensions, allowUnusedPatches: opts.allowUnusedPatches, catalogs: opts.catalogs, nodeVersion: opts.nodeVersion ?? process.version.slice(1), // ... resolutionMode / minimumReleaseAge / trustPolicy 等策略字段 lockfile: opts.lockfile, })可见patchedDependencies、packageExtensions、allowUnusedPatches与overrides、catalogs一样属于随请求携带的项目上下文而不仅是解析开关。请求通过postResolve发送到/-/pnpr/v0/resolve支持 HTTP/HTTPS、gzip 压缩、10 分钟超时、可选的Authorization头。3.3 校验函数返回的 lockfile 必须保留变换客户端拿到服务端返回的 lockfile 后assertTransformMetadataresolveViaPnprServer.ts#L226-L239会对变换信息做严格校验function assertTransformMetadata ( lockfile: LockfileFile, opts: PickResolveViaPnprServerOptions, patchedDependencies | packageExtensions ): void { const expectedPatches opts.patchedDependencies if (expectedPatches ! null Object.keys(expectedPatches).length 0 !equalStringRecords(lockfile.patchedDependencies, expectedPatches)) { throw new PnpmError(PNPR_TRANSFORM_METADATA_MISMATCH, pnpr server /-/pnpr/v0/resolve returned patchedDependencies that do not match the request; the server may not support project transforms) } const expectedExtensionsChecksum hashObjectNullableWithPrefix(opts.packageExtensions) if (expectedExtensionsChecksum ! null lockfile.packageExtensionsChecksum ! expectedExtensionsChecksum) { throw new PnpmError(PNPR_TRANSFORM_METADATA_MISMATCH, pnpr server /-/pnpr/v0/resolve returned packageExtensionsChecksum that does not match the request; the server may not support project transforms) } }它做两件事逐项比对patchedDependencies服务端返回的 lockfile 中patchedDependencies记录必须与请求完全一致equalStringRecords比较键数与每个键值见 resolveViaPnprServer.ts#L241-L247比对packageExtensionsChecksum用pnpm/crypto.object-hasher的hashObjectNullableWithPrefix对本地packageExtensions计算校验和与服务端写入 lockfile 的校验和比对。任一不匹配即抛出PNPR_TRANSFORM_METADATA_MISMATCH错误提示服务器可能不支持项目变换the server may not support project transforms。这意味着旧版或不支持变换的服务端会被快速失败fail fast拦截而不是静默产出丢失补丁的 lockfile——这正是 changeset 名称中 safe安全二字的含义。四、服务端侧接收、识别并应用变换4.1 线上协议字段服务端的请求结构体ResolveRequest定义了对应的两个字段pnpr/crates/pnpr/src/resolver/protocol.rs#L145-L153/// The clients patchedDependencies, with local file paths replaced by /// their SHA-256 hashes. Resolution uses the hashes in package snapshot /// keys; patch application remains client-side. #[serde(default)] pub patched_dependencies: OptionIndexMapString, String, /// The clients packageExtensions, applied to dependency manifests /// during server-side resolution. #[serde(default)] pub package_extensions: OptionIndexMapString, PackageExtension,Rust 端注释确认了关键设计哈希化客户端把本地补丁文件路径替换为 SHA-256 哈希后上行解析时哈希被用于 package snapshot 的键职责边界补丁的实际应用patch application仍在客户端完成服务端只在解析阶段认得出哪些包被打过补丁package_extensions在服务端解析期间直接应用到依赖 manifest 上从而影响依赖图的构建。4.2 判定逻辑何时必须走完整解析服务端在resolve.rs中通过config_transforms_lockfile判断当前配置是否会以 lockfile 无法自行校验的方式改写依赖图pnpr/crates/pnpr/src/resolver/resolve.rs#L288-L302fn config_transforms_lockfile(config: Config) - bool { config.package_extensions .as_ref() .is_some_and(|extensions| !extensions.is_empty()) || config.ignored_optional_dependencies .as_ref() .is_some_and(|patterns| !patterns.is_empty()) || config.patched_dependencies .as_ref() .is_some_and(|map| !map.is_empty()) || config.patched_dependency_hashes_override .as_ref() .is_some_and(|map| !map.is_empty()) || config.inject_workspace_packages }只要package_extensions、patched_dependencies或哈希覆盖任一非空服务端就判定配置变换了 lockfile从而走完整解析路径而不是复用旧 lockfile 的快捷路径。这与变更集的意图一致变换信息一旦存在解析结果就必须重新计算以确保补丁与包扩展被正确纳入。五、安全边界变换信息不得突破 fetch 边界pnpr 作为托管解析服务必须防范恶意请求利用变换信息发起越权请求。测试 pnpr/crates/pnpr/src/resolver/tests/behavior.rs#L204-L230 中的package_extensions_stay_inside_the_fetch_boundary专门验证这一点#[test] fn package_extensions_stay_inside_the_fetch_boundary() { let context RouteContext::from_config(registry_config()); let off_allowlist serde_json::from_value::ResolveRequest(serde_json::json!({ packageExtensions: { foo1.0.0: { optionalDependencies: { bar: https://169.254.169.254/bar.tgz // 云元数据地址恶意示例 } } } })) .expect(package extension request parses); let inline_auth serde_json::from_value::ResolveRequest(serde_json::json!({ packageExtensions: { foo1.0.0: { peerDependencies: { bar: https://user:passregistry.example.test/bar.tgz // 内联凭据 } } } })) .expect(package extension request parses); assert!(reject_off_allowlist_fetches(off_allowlist, context).is_some()); assert!(reject_inline_url_auth(inline_auth).is_some()); }该测试构造了两个攻击面并断言都会被拒绝越权地址在packageExtensions中注入指向非允许列表off-allowlist的 URL示例中的169.254.169.254是云厂商元数据地址防止 SSRF 类攻击内联凭据在扩展依赖的 URL 中内嵌user:pass形式的认证信息防止凭据被带入服务端请求。这说明该变更在放开变换信息上行能力的同时服务端对这类信息中携带的 URL 保持严格的白名单与凭据校验保证补丁/扩展机制不会变成越权访问的跳板。六、与安装流程的联动从配置到 lockfile 设置客户端安装协调器pnpm/installing.deps-installer是本变更的另一侧它在把解析任务交给 pnpr 之前先完成变换信息的本地计算并把它纳入 lockfile 设置变更检测。在 pnpm11/installing/deps-installer/src/install/index.ts 中可以看到完整的计算链条const packageExtensionsChecksum hashObjectNullableWithPrefix(opts.packageExtensions) // L707 const resolvedPatchedDeps resolvePatchedDependencies(opts.patchedDependencies, opts.lockfileDir) // L709 const patchedDependencies opts.ignorePackageManifest ? ctx.wantedLockfile.patchedDependencies : (resolvedPatchedDeps ? await calcPatchHashes(resolvedPatchedDeps) : {}) // L710-712 const patchGroups groupPatchedDependenciesWithPaths(patchedDependencies, resolvedPatchedDeps) // L713要点packageExtensionsChecksum通过hashObjectNullableWithPrefix计算与服务端校验时使用同一哈希函数index.ts#L707resolvePatchedDependencies把补丁配置解析为具体文件路径再由calcPatchHashes计算哈希——这正是转发给 pnpr 的那份哈希化数据index.ts#L709-L712。随后patchedDependencies与packageExtensionsChecksum一起进入lockfileSettingsindex.ts#L769-L776参与getOutdatedLockfileSettings的变更检测补丁集合变化会触发changedLockfileSettings中的patchedDependencies项进而把drift.patchedDependencies置为 trueindex.ts#L817-L824使快更新路径让位给完整解析保证补丁变更一定被重新解析并写入 lockfile。七、小结一次端到端的变换保真闭环汇总本次变更的完整数据链路客户端收集pnpm/installing.deps-installer把本地补丁文件哈希化为patchedDependencies映射并计算packageExtensionsChecksum线上转发pnpm/pnpr.client在/-/pnpr/v0/resolve请求体中携带patchedDependencies、packageExtensions与allowUnusedPatches服务端应用pnpm/pnpr依据config_transforms_lockfile判定需完整解析在解析过程中把补丁哈希写入 snapshot 键、把包扩展应用到依赖 manifest客户端校验返回的 lockfile 必须逐项匹配请求中的patchedDependencies与packageExtensionsChecksum否则以PNPR_TRANSFORM_METADATA_MISMATCH快速失败安全兜底包扩展中携带的 URL 受 fetch 白名单与凭据校验约束不允许越权取包。从 .changeset/safe-pnpr-project-transforms.md 的一行摘要出发可以看到仓库为该语义配齐了协议字段protocol.rs、解析判定resolve.rs、安全测试behavior.rs与客户端校验resolveViaPnprServer.ts——服务端解析保留补丁与包扩展由此从一句承诺落地为可验证、可防御的实现。对于升级到含此变更的 pnpm/pacquet 版本的用户无需修改任何配置即可获得一致的服务端解析行为唯一可见的变化是若连接到一个尚未支持项目变换的 pnpr 服务器客户端会给出明确的PNPR_TRANSFORM_METADATA_MISMATCH报错而不是默默产出丢失补丁的 lockfile。赞分享包管理器开发工具CLI【免费下载链接】pnpmFast, disk space efficient package manager项目地址https://gitcode.com/gh_mirrors/pn/pnpm点击查看免费下载相关推荐Erlangshen-Roberta-110M-Similarity API接口设计快速集成到现有系统的完整方案Erlangshen Roberta 110M Similarity API接口设计快速集成到现有系统的完整方案 想要为你的应用添加智能中文文本相似度计算功能包管理器开发工具CLIpnpm 精确版本固定符 操作符在 pnpm update 中的保留机制与实现解析pnpm 精确版本固定符 操作符在 pnpm update 中的保留机制与实现解析 导读 在使用 pnpm 管理依赖时如果你在 package.jso包管理器开发工具CLI上一篇如何为Massive贡献代码开源项目参与指南与最佳实践下一篇如何永久保存微信聊天记录WeChatMsg让你的数字记忆不再丢失创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考