Puppeteer 版本演进全景：解读 CHANGELOG 结构、release-please 发布机制与浏览器版本映射
Puppeteer 版本演进全景解读 CHANGELOG 结构、release-please 发布机制与浏览器版本映射【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerPuppeteer 仓库根目录的 CHANGELOG.md 是puppeteer与puppeteer-core两个包的合并变更日志覆盖从 2020-11 的 5.5.0 到 2026-08 的 25.8.0 的完整发布历史。本文以该文件为主体讲清它的章节结构与分类规范、由 release-please 与合并脚本驱动的生成机制、各版本的关键特性与破坏性变更以及它与 versions.json 中浏览器版本钉选pin之间的对应关系帮助你在升级依赖、排查问题、追踪新特性落地版本时快速利用这份变更日志。一、合并 Changelog 是什么两个包的历史合为一处根目录 CHANGELOG.md 的第一行标题下就写明了它的定位# Changelog Combined changelog for puppeteer and puppeteer-core.也就是说开发者在 npm 上看到的puppeteer含浏览器下载能力的完整包和puppeteer-core纯 API、不带浏览器下载逻辑的核心包在发布层面被当作同一个版本组每个版本号只出现一次两个包各自条目下的改动被归并到同一个版本区块中。这份文件约 6400 行最新的版本区块是## 25.8.0 (2026-08-17)最早的版本区块为 5.5.02020-11-16。每个版本区块由若干###小节组成小节内逐条列出提交说明、对应的 issue/PR 编号与 commit 短哈希。这种一条改动 一个 PR commit的颗粒度使得 Changelog 天然具备可检索性你可以直接按关键词如roll to Chrome、executablePath定位某个行为变化的引入版本。二、章节分类规范从 Conventional Commits 到表情符号小节观察任意版本区块会发现小节标题高度统一小节标题对应 Conventional Commits 类型含义### ⚠ BREAKING CHANGES!破坏性标记该版本包含不兼容变更升级前必读### Featuresfeat新增功能### ️ Fixesfix缺陷修复### Documentationdocs文档更新### ⚡ Performanceperf性能优化### ️ Refactorrefactor不改变行为的代码重构### ♻️ Choreschore/test日常维护与测试类提交### Dependenciesworkspace 依赖联动记录 monorepo 内依赖包的联动升版这套commit type → 小节名的映射不是手写的而是由 release-please-config.json 显式声明的changelog-sections字段生成changelog-sections: [ {type: feat, section: Features, hidden: false}, {type: fix, section: ️ Fixes, hidden: false}, {type: docs, section: Documentation, hidden: false}, {type: perf, section: ⚡ Performance, hidden: false}, {type: refactor, section: ️ Refactor, hidden: false}, {type: chore, section: ♻️ Chores, hidden: true}, {type: test, section: ♻️ Chores, hidden: true}, {type: build, section: ⚙️ Automation, hidden: true}, {type: ci, section: ⚙️ Automation, hidden: true} ]其中hidden: true的小节默认不会出现在 changelog 中只有在确有对应提交时才展示。值得注意的是chore与test合并映射到了同一个♻️ Chores小节而build/ci映射到隐藏的⚙️ Automation。此外还有一个不在映射表里、但频繁出现的固定小节### Dependencies内容形如### Dependencies * The following workspace dependencies were updated * dependencies * puppeteer/browsers bumped from 3.2.0 to 3.2.1它记录的是 monorepo 内部的工作区依赖联动当puppeteer/browsers或puppeteer-core升版时依赖方会跟着 bump并在此留痕。阅读 Changelog 时这个区块能帮你判断某次功能/修复实际上来自哪个子包。三、发布机制release-please 如何驱动整个 Changelogdocs/contributing.md 的 Releasing to npm 一节说明了发布流程项目使用 release-please 自动发布当需要发版时只需合并 release-please 自动生成的 release PR 即可。整个过程与 Changelog 的关系如下提交约定PR 标题遵循 Conventional Commitsfeat:、fix:、perf:、refactor:等release-please 据此把提交归入上表对应的小节版本组联动release-please-config.json 中的linked-versions插件把puppeteer与puppeteer-core编为名为puppeteer的组{ type: linked-versions, group-name: puppeteer, components: [puppeteer, puppeteer-core] }这解释了为什么两个包永远同版本号如 25.8.0且 release PR 的 compare 链接形如puppeteer-v25.7.0...puppeteer-v25.8.0工作区包管理node-workspace插件merge: false负责处理 packages/ 下的各个独立包如puppeteer/browsers、ng-schematics后者配置了bump-minor-pre-major: true与独立 PR版本号文件自动改写extra-files声明了 release 时需要自动更新版本号的文件例如puppeteer-core的 packages/puppeteer-core/src/util/version.ts// If moved update release-please config // x-release-please-start-version export const packageVersion 25.8.0; // x-release-please-end成对的x-release-please-start-version/x-release-please-end标记让 release-please 能定位并替换版本号根 Herebyfile.mjs 与 browsers 包的src/CLI.ts也在类似机制的维护范围内。四、合并脚本tools/merge-changelogs.ts 的两包归并逻辑两个子包各自也有 changelogpackages/puppeteer/CHANGELOG.md 与 packages/puppeteer-core/CHANGELOG.md。根目录这份Combined changelog由 tools/merge-changelogs.ts 归并生成脚本逻辑可以直接对照阅读按版本区块解析parseChangelog以## [x.y.z]正则切分文件为若干Version对象含version、header、lines解析不到语义化版本号会直接抛错按小节归并去重mergeVersions把两个包同版本条目中的###小节标题作为键小节内的每条 bullet 放入Set去重——因此同一改动即使同时出现在两个包的 changelog 里合并后只会出现一次输出顺序以puppeteer的区块顺序为骨架逐版本查找puppeteer-core中同版本区块进行合并最终写回根目录CHANGELOG.md。const puppeteerChangelog parseChangelog(./packages/puppeteer/CHANGELOG.md); const puppeteerCoreChangelog parseChangelog( ./packages/puppeteer-core/CHANGELOG.md, ); ... for (let entry of puppeteerChangelog) { for (const coreEntry of puppeteerCoreChangelog) { if (coreEntry.version entry.version) { entry mergeVersions(entry, coreEntry); } } combinedChangelog.push(entry.header); combinedChangelog.push(...entry.lines); } writeFileSync(./CHANGELOG.md, combinedChangelog.join(\n));合并完成后根 Herebyfile.mjs 的docsTask会把这份 Combined changelog 复制到文档站点并对 MDX 做转义{→\{// Copy combined changelog. let changelog await readFile(CHANGELOG.md, utf-8); // Escape for MDX. changelog changelog.replaceAll({, \\{); await writeFile(docs/CHANGELOG.md, changelog);所以文档站上的 docs/CHANGELOG.md 与根 CHANGELOG.md 内容一致只是多了 MDX 转义。理解这条子包 changelog → 脚本合并 → 文档站同步的流水线就能明白为什么根文件头三行是固定的# Changelog与 Combined changelog 说明——它们由脚本硬编码生成而非人工撰写。五、版本里程碑从 Changelog 中读出的重大变更结合变更日志下面梳理若干对使用者影响最大的节点。所有条目均可在 CHANGELOG.md 中按版本标题检索到原文。25.0.02026-05-12一次集中的破坏性变更清理这是 Changelog 中破坏性变更最集中的版本⚠ BREAKING CHANGES小节列出了 9 项移除Puppeteer.product#14977 对应提交PR 编号见原文档最低 Node.js 版本提升到 22executablePath、defaultArgs改为返回 Promise原为同步字符串/数组移除MouseOptions.clickCount最低版本要求Node v20.19 与 TypeScript v5.0.1过渡性要求随后又提到 Node 22移除Browser.isConnected()包全面转为 ESM only移除 Cookie 的sameParty属性puppeteer-core范围;换行符分隔的响应头统一归一化为逗号分隔格式。如果你维护着 24.x → 25.x 的升级路径这一节的每一条都意味着需要排查的 API 调用点尤其是await语义变化executablePath()/defaultArgs()由同步变异步与 ESM 迁移。更早的历史性节点8.0.02021-02-26类型重命名ChromeArgOptions→BrowserLaunchArgumentOptions、BrowserOptions→BrowserConnectOptions7.0.02021-02-03page.screenshot开始使用captureBeyondViewport截图像素不再被 viewport 裁剪语义约束BREAKING6.0.02021-02-02内置aria/选择器不再返回被忽略的元素BREAKING并新增page.emulateNetworkConditions。近期版本25.1.0 — 25.8.0的功能主线从近 8 个版本的 Features小节可以看到几条清晰的产品主线PWA 支持落地到浏览器级 API25.4.0 引入 browser 级 PWA install/launch/uninstall API配套文档见 docs/api/puppeteer.browser.installpwa.md资源管理现代化25.4.0 暴露 Explicit Resource Managementusing语法配合 docs/api/puppeteer.asyncdisposesymbol.md 中定义的AsyncDisposeSymbolBrowser/Page等对象可用using声明自动释放25.5.0 起引入Dialog的handledgetter 与状态跟踪扩展Extensions体系扩展25.2.0 允许扩展通过 WebSocket 运行25.3.0 支持为 browser context 安装扩展24.41.0 起新增列出已装扩展、触发扩展动作的 API对应 docs/api/puppeteer.browser.extensions.mdWebMCPWeb 模型上下文协议系列24.40.x—24.41.0 连续多笔提交从工具注册检查、execute 支持到调用/响应钩子逐步成型网络治理24.42.0 引入 URL blocklist24.43.0 引入 allowlist24.43.1 修复了 BiDi URL 限制拒绝逻辑25.0.0 起当 allowlist/blocklist 生效时阻止标准网络模拟重置。可观测性25.6.0 将自定义Logger暴露到launch/connect25.7.0 修复 logger 调用导致的崩溃tracing.start支持bufferSize选项对应 docs/api/puppeteer.tracingoptions.md。而️ Fixes小节中反复出现的roll to Chrome x.y/roll to Firefox x.y条目则构成了第六节要讲的浏览器版本钉选轨迹。六、Changelog 与浏览器版本钉选的对应关系Puppeteer 发布时会钉选一个 Chrome 与一个 Firefox 构建。Changelog 中的roll to Chrome/Firefox ...条目出现在 Features 或 Fixes 小节记录了每次钉选的变化例如 25.7.0 的 roll to Chrome 152.0.7977.42 与 roll to Firefox 153.0.4。这些钉选结果在仓库根的 versions.json 中有完整机器可读的映射每个条目形如[ v25.7.0, { chrome: 152.0.7977.42, firefox: stable_153.0.4 } ]两条使用要点升级前先查钉选从 versions.json 找到目标 Puppeteer 版本对应的浏览器版本可预判浏览器侧的行为差异渲染、DevTools 协议能力等。例如v25.7.0对应 Chrome 152.0.7977.42 / Firefox stable_153.0.4v24.43.1对应 Chrome 148.0.7778.97 / Firefox stable_150.0.2NEXT 条目与最低维护版本文件首部的NEXT条目Chrome 152.0.7977.54 / Firefox stable_154.0代表当前开发线即将钉选的版本lastMaintainedChromeVersion149.0.7827.22则标明了仍在维护的最低 Chrome 版本。从源码结构看这两个字段服务于浏览器构建缓存与可下载版本的维护策略。另外### Dependencies小节中puppeteer/browsers bumped from X to Y的升版记录与 Changelog 中的 roll 条目相互印证每次浏览器钉选变化通常伴随puppeteer/browsers的联动升级。七、实战如何用这份 Changelog 高效排障与升级定位特性落地版本拿到一个 API如browser.installPWA、locator.fill支持 checkbox/radio在 CHANGELOG.md 中按名称搜索第一条命中的版本即最低可用版本。例如 support checkboxes and radios in locator.fill 出现在 24.43.0add browser-level PWA install/launch/uninstall APIs 出现在 25.4.0升级前扫描 BREAKING对目标区间的每个## [x.y.z]区块检查是否存在### ⚠ BREAKING CHANGES小节25.0.0 是唯一的大版本破坏点24.x → 25.x 的迁移应按第五节清单逐项排查追踪行为变化的修复版本把线上问题现象如 screencast 回放时间不对、logger 导致崩溃翻译成关键词检索。前者对应 25.2.0 的 correct screencast frame timing so playback matches real time后者对应 25.7.0 的 logger calling causing crashes——找到版本后即可将依赖下限锁定到修复版本判断改动来自哪个包同版本条目中若只有puppeteer-core侧提交如 25.0.0 的 Remove Cookie attribute sameParty 带puppeteer-core:scope说明该变化在 core 包即生效puppeteer包随 workspace 依赖同步获得验证浏览器兼容范围结合 versions.json 的钉选映射确认你升级前后使用的 Chrome/Firefox 构建必要时用 packages/browsers 提供的npx puppeteer/browsers安装对应构建做回归。八、小结CHANGELOG.md 不只是一份记录它是 Puppeteer 发布体系的单一事实来源由 Conventional Commits 驱动、经 release-please-config.json 定义的章节规范格式化再由 tools/merge-changelogs.ts 将 packages/puppeteer/CHANGELOG.md 与 packages/puppeteer-core/CHANGELOG.md 按版本小节去重合并最后经 Herebyfile.mjs 的 docs 任务同步到文档站。配合 versions.json 的浏览器钉选映射与 docs/contributing.md 的发布流程说明你可以完整重建一次 PR 合并如何变成一次带浏览器钉选的 npm 发布的全过程。对于使用者这份 Changelog 加上下文给出的检索方法就是升级决策与问题归因的第一手资料。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考