包管理器开发工具CLI【免费下载链接】pnpmFast, disk space efficient package manager项目地址https://gitcode.com/gh_mirrors/pn/pnpm点击查看免费下载导读minimumReleaseAge发布年龄限制是 pnpm 用来延迟安装新发布版本、降低供应链风险的解析策略只有发布时间早于某个截止时间的版本才会被选中。但当某个 dist-tag例如latest或自定义的nightly指向的版本因过于年轻被过滤掉时pnpm 需要把该 tag 回退到一个仍在保留集合中的版本——而此前的回退逻辑可能选中一个比注册表原始 tag 目标版本号更高的版本与本该先延迟、后使用的保守策略相悖。本文基于 pnpm 仓库中的 changeset 声明.changeset/chilly-foxes-brush.md结合pnpm/resolving.registry.pkg-metadata-filter包的源码与测试完整讲解该修复的实现原理、tag 回退的候选分级算法以及minimumReleaseAge相关设置的实际用法。读完本文你将掌握发布年龄过滤的完整数据流理解 dist-tag 回退时不超过原始 target的边界约束是如何在代码层强制执行的。修复声明一次针对自定义 dist-tag 回退的 patch该 changeset 以patch级别同时作用于三个发布单元pnpm/resolving.registry.pkg-metadata-filterpacquetpnpm 生态中的 Rust 重写实现pnpm本体其修复内容原文为FixedminimumReleaseAgefallback for custom dist-tags so the selected version does not exceed the registry’s original tag target.即修复了自定义 dist-tag如nightly、beta、next等非latest标签在minimumReleaseAge过滤下的回退逻辑确保回退选中的版本不会超过注册表原始 tag 所指向的版本。要理解这句话的含义需要先厘清三个概念minimumReleaseAge的截止时间cutoff、dist-tag 的原始目标original tag target以及回退fallback发生的场景。前置机制minimumReleaseAge 是如何工作的minimumReleaseAge是 v10.16.0 加入、在 v11 中默认值为1440 分钟24 小时的解析设置单位是分钟作用于包括传递依赖在内的所有依赖。其官方语义见 pnpm11/docs/settings/dependency-resolution.md降低安装到被入侵或有缺陷的包的风险可以延迟安装新发布的版本。大多数恶意发布会在一个小时内被发现并下架。配置方式是在pnpm-workspace.yaml中声明minimumReleaseAge: 1440与之配套的设置还有minimumReleaseAgeExcludestring[]默认 undefined按包名或模式如myorg/*豁免某些依赖也可精确到版本nx21.6.5、webpack4.47.0 || 5.102.1minimumReleaseAgeIgnoreMissingTimeBoolean默认 true当注册表元数据缺少time字段时跳过年龄检查minimumReleaseAgeStrictBoolean默认显式配置时 true当范围内没有任何版本满足年龄约束时为false则回退到不满足约束的版本以保证安装继续为true则直接解析失败。从解析数据流看pnpm 会把当前时间 - minimumReleaseAge 分钟计算为一个截止时间publishedBy/cutoff然后对每个包的 packument注册表返回的完整元数据文档执行过滤只保留time[version] cutoff的版本同时把每个 dist-tag 移动到仍被保留的最佳版本上。问题场景dist-tag 目标被年龄过滤击穿dist-tag 是注册表给包打的别名例如latest、next、nightly、beta。正常情况下latest指向包的最新稳定版本自定义 tag 指向某个特定发布流的最新版本。当minimumReleaseAge启用后会发生如下冲突注册表原始元数据中dist-tags.latest 3.0.1发布时间为2026-07-15T12:00:00Z而截止时间是2026-07-15T00:00:00Z3.0.1因太年轻被过滤掉此时 pnpm 必须把latest回退到仍在保留集合中的某个版本例如3.0.0或4.0.0。问题在于回退的方向约束如果4.0.0虽然发布时间足够早比如2025-10-10但其版本号高于原始 tag 目标3.0.1那么在延迟发布的语义下选中它同样不妥——因为它实际上是一个更新的大版本用户本来没有明确要求安装它。修复的目标就是让回退只向下、不向上所选版本不能超过注册表原始 tag 指向的版本号。这一点在latest上其实已有约束latest只能回退到同主版本或更低主版本但自定义 tagnightly、beta等此前缺乏同等保护可能回退到高于原始目标的版本。本次 changeset 修复的正是这一盲区。核心实现过滤与 dist-tag 回退算法修复发生在pnpm/resolving.registry.pkg-metadata-filter包中主文件是 pnpm11/resolving/registry/pkg-metadata-filter/src/index.ts。整个包对外只暴露两个函数filterPkgMetadataByPublishDate(pkgDoc, publishedBy, trustedVersions?)按发布时间截止点过滤 packument并修正 dist-tagsfilterPkgMetadataVersions(pkgDoc, keep)通用的按保留谓词过滤版本 修正 dist-tags函数是前者的底层。过滤主流程function filterPkgMetadataByPublishDateUncached ( pkgDoc: PackageMetadataWithTime, publishedBy: Date, trustedVersions?: string[] ): PackageMetadataWithTime { return filterPkgMetadataVersions(pkgDoc, (version) { const timeStr pkgDoc.time[version] return Boolean(timeStr new Date(timeStr) publishedBy) || trustedVersions?.includes(version) true }) }保留规则一目了然版本的发布时间必须不晚于截止时间或者该版本在trustedVersions豁免清单中对应minimumReleaseAgeExclude命中的版本。filterPkgMetadataVersions随后做两件事过滤版本表用Object.defineProperty逐键复制 property descriptor 而非读取值这是刻意的性能设计——npm-resolver 的 mirrorLayout 可能为每个版本注册惰性 getter首次访问时才解析 manifest直接读值会提前解析所有被保留版本的 manifest重算 dist-tags对每个 tag若原目标仍被保留则原样保留否则在保留集合中寻找最佳替代见下。dist-tag 回退的边界约束回退的核心在resolveKeptDistTags→findBestTagCandidate→evaluateTagCandidate这条链上其中最关键的一行是if (!candidateParsed || candidateParsed.compare(originalSemVer) 0) return undefinedoriginalSemVer是注册表原始 tag 目标版本的 semver 解析结果。任何compare(originalSemVer) 0的候选——即版本号高于原始目标的版本——都会被直接排除无论其发布时间是否满足约束。这正是 changeset 所描述的所选版本不超过注册表原始 tag 目标在代码层的强制实现且它对所有 tag包括自定义 tag一视同仁。候选分级SameLane / PrereleaseOfMajor / LowerMajor在不高于原始目标的硬边界内回退候选还要按语义贴近程度分级由getTagCandidateTier决定分级定义在 pnpm11/resolving/registry/pkg-metadata-filter/src/index.ts层级名称条件说明2SameLane候选与目标具有相同的 prerelease 性质且主版本相同最贴近原 tag 语义的选择1PrereleaseOfMajor候选是目标主版本上的 prerelease且版本低于目标例如目标1.0.0被过滤后1.0.0-beta.4优于任何低主版本的稳定版0LowerMajor仅latest可用的跨主版本回退候选与目标同为稳定或同为 prerelease但主版本更低设计注释给出了一个直观的例子当1.0.0太新时latest应回退到它此前指向过的1.0.0-beta.4而不是0.0.1。也就是说先保证语义同轨同主版本、同 prerelease 性质再比较版本号大小。比较时还遵循一条附加规则candidateIsBetter层级更高者胜层级相同则版本号更大者胜若版本号更大者带deprecated标记而较小者没有则优先选择未废弃的版本bestVersionIsDeprecated !candidateIsDeprecated。这保证了回退结果不会明知废弃还用。测试验证与修复一一对应的用例该包在 pnpm11/resolving/registry/pkg-metadata-filter/test/index.ts 中提供了完整测试。其中两个用例直接验证本次修复用例一latest 回退不超过原始 targettest(latest fallback does not exceed the original dist-tag target, () { const cutoff new Date(2026-07-15T00:00:00.000Z) // versions: 3.0.0 (07-01 发布), 3.0.1 (07-15 12:00 发布latest 原指向), // 4.0.0 (2025-10-10 发布发布时间满足但版本号更高) // dist-tags: { latest: 3.0.1 } expect(filtered[dist-tags].latest).toBe(3.0.0) // 无安全回退时versions 只剩 3.0.1 与 4.0.0 expect(withoutSafeFallback[dist-tags].latest).toBeUndefined() })注意第二个断言当保留集合中只有3.0.1已被过滤和4.0.0高于原始 target时回退结果是undefined——宁可丢弃该 tag也不越过边界。用例二自定义 dist-tag 回退不超过原始 target与 changeset 直接对应test(custom dist-tag fallback does not exceed the original target, () { // versions: 0.0.29-nightly.20260724.896 (07-24 发布) // 0.0.29-nightly.20260725.899 (07-25 发布nightly 原指向) // 0.1.0-alpha.1 (2026-02-28 发布发布时间满足但版本号更高) // dist-tags: { nightly: 0.0.29-nightly.20260725.899 } expect(filtered[dist-tags].nightly).toBe(0.0.29-nightly.20260724.896) })这是最贴合 changeset 字面描述的回归测试nightly原指向的0.0.29-nightly.20260725.899太年轻被过滤后回退选择的是同日更早的同一个发布流版本0.0.29-nightly.20260724.896而不是发布时间虽旧、但版本号更高主版本升到0.1.0的0.1.0-alpha.1。其余三个用例覆盖了配套行为latest fallback prefers a prerelease of the new major over a lower major验证层级排序——目标1.0.0太新时1.0.0-beta.4PrereleaseOfMajor优先于0.0.1LowerMajor同时验证废弃候选会被跳过1.0.0-beta.3带deprecated: broken时回退到0.0.1latest fallback prefers a stable version of the same major over a prerelease同主版本时稳定版1.4.0SameLane优先于1.5.0-rc.1快照测试在 test/snapshots/index.ts.snap 中固化了两组过滤结果——被过滤的3.2.0从versions消失、latest从3.2.0回退到3.0.0、time字段原样保留。调用链过滤结果如何进入版本选择该过滤函数由 npm-resolver 在解析流程中调用。在 pnpm11/resolving/npm-resolver/src/pickPackageFromMeta.ts 中publishedByExclude来自minimumReleaseAgeExclude的匹配结果先于过滤处理若整个包被豁免excludeResult true直接返回原始meta跳过过滤若meta.time缺失标记needsFullMetadata: true交由上层补取完整元数据对应minimumReleaseAgeIgnoreMissingTime的行为否则调用filterPkgMetadataByPublishDate(meta, publishedBy, trustedVersions)其中trustedVersions是豁免精确版本如nx21.6.5对应的版本列表——它们会绕过年龄过滤但仍然参与 dist-tag 回退的边界判断。过滤后的 packument 随即被pickVersionByVersionRange等版本选择函数使用因此dist-tags的重算结果直接决定latest/自定义 tag 依赖最终解析到哪个版本。工程细节记忆化缓存与原型污染防护除功能正确性外该模块还包含两个值得注意的工程细节按 packument 分组的策略缓存每次安装中每个依赖边都会触发一次 pick同一个 packument 会以相同截止时间被反复过滤。而过滤会新建版本表并为每个版本解析一次Date代价不低。因此filterPkgMetadataByPublishDate用WeakMapPackageMetadataWithTime, Mapstring, ...做记忆化缓存键是cutoff的时间戳外加trustedVersions列表因为共享的元数据缓存可能服务于不同策略的安装而非 Date 对象引用每个 packument 的策略缓存上限为MAX_POLICIES_PER_PACKUMENT 4超过后按插入顺序淘汰最旧策略——防止长期运行的 store server / daemon 进程在每个安装计算新 cutoff、共享元数据缓存长期存活的场景下无限增长。对应测试用例为filtering is memoized per packument and the per-packument policy cache stays bounded。__proto__原型污染防护过滤后versions与dist-tags都使用Object.create(null)创建确保从 JSON 解析的 packument 中名为__proto__的版本或 tag 仍然作为自有键保留而不会成为新对象的原型、将恶意 manifest 的字段泄漏为版本号。测试a version or dist-tag named __proto__ stays an own key of the filtered metadata专门验证了这一行为断言polluted in filtered.versions为false。使用建议与总结若你启用了minimumReleaseAge且依赖通过latest之外的自定义 tagnightly、beta、next等安装本修复保证年龄过滤后的解析结果始终保守向下既不选太年轻的版本也不越级选到比 tag 原始指向更高版本的包。升级包含该 patch 的 pnpm或使用同步了修复的 pacquet即可生效无需改动配置。需要立即使用新版本时用minimumReleaseAgeExclude精确豁免webpack4.47.0 || 5.102.1比调大minimumReleaseAgeStrict更精细。关注dist-tags回退结果的边界行为当保留集合中没有任何不高于原始 tag 目标的版本时pnpm 会选择丢弃该 tag测试中断言latest为undefined而不是越界选择。若你的工作流依赖此类 tag 的可用性应留意解析结果变化。围绕一次 changeset 修复本文完整覆盖了它的触发场景minimumReleaseAge年龄过滤、算法约束compare(original) 0排除 三级候选分层、回归测试五个专项用例与外围机制豁免列表、记忆化缓存、原型污染防护。相关源码均可继续深入过滤模块、调用方、设置文档、测试套件。赞分享包管理器开发工具CLI【免费下载链接】pnpmFast, disk space efficient package manager项目地址https://gitcode.com/gh_mirrors/pn/pnpm点击查看免费下载相关推荐pnpm self-update 修复minimumReleaseAge 成熟度截断不再让 dist-tag 更新意外降级pnpm self update 修复minimumReleaseAge 成熟度截断不再让 dist tag 更新意外降级 pnpm self update包管理器开发工具CLIrepghostnet_111.in1k实战教程从零开始构建图像分类应用repghostnet_111.in1k实战教程从零开始构建图像分类应用 欢迎来到这份终极repghostnet_111.in1k实战教程 本文将带你从pnpm trustPolicy 与 minimumReleaseAge 的 missing-time 处理修复详解minimumReleaseAgeIgnoreMissingTime 的语义边界pnpm trustPolicy 与 minimumReleaseAge 的 missing time 处理修复详解minimumReleaseAgeIgno包管理器开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
