Puppeteer 中文文档v25.8.0

参与贡献

首先，感谢你对 Puppeteer 的关注！我们非常乐意接受你的 补丁和贡献！

贡献者许可协议

对本项目的贡献必须附有贡献者许可协议（Contributor License Agreement）。你（或你的雇主）保留对你贡献的版权， 这只是授予我们把你的贡献作为项目的一部分来使用和重新分发的许可。 前往 <https://cla.developers.google.com/> 查看 你当前的协议或签署新协议。

你通常只需要提交一次 CLA，所以如果你已经提交过一次 （即使是为其他项目），你可能不需要再次提交了。

快速开始

  1. 克隆此仓库

    git clone https://github.com/puppeteer/puppeteer
cd puppeteer

    或

    在 GitHub Codespaces 中打开

  2. 安装依赖

    npm install
# Or to download Firefox by default
PUPPETEER_BROWSER=firefox npm install

  3. 构建所有包

    npm run build

  4. 运行所有测试

    npm test

构建单个包

要构建单个包，可以运行：

npm run build --workspace <package> # e.g. puppeteer

这会自动构建所有依赖的包，因此指定单个包就足够了。这一切都归功于 wireit，它的行为类似于 GNU Make。

监听模式

要持续构建某个包，可以运行：

npm run build --watch --workspace <package> # e.g. puppeteer

你只能指定一个要监听的包，否则事情不会按预期工作。 如上所述，由于 wireit 的存在，当发生变化时， 所有依赖都会被构建或重新构建（如果需要）。

清理过期产物

某些生成的产物（例如 packages/puppeteer-core/src/types.ts）可能会过期，因为这些产物 依赖于构建系统无法捕获的复杂条件（例如不同文件的名称）。要清理产物，可以运行

npm run clean
# or specify the package
npm run clean --workspace <package>

全面测试

除了 npm test 之外，还有几个其他 npm 脚本， 通常通过 CI 检查：

  • test-install - 测试 puppeteer 和 puppeteer-core 是否正确 安装并可用。
  • test-types - 使用 tsd 测试 puppeteer 中的 TypeScript 类型。
  • test:chrome:** - 在 Chrome 上测试 puppeteer。
  • test:firefox:** - 在 Firefox 上测试 puppeteer。
  • unit - 运行单元测试。

默认的 npm test 会运行 test:{chrome,firefox}:headless，这通常 就足够了。

Puppeteer 使用基于 Mocha 的自定义测试运行器，它会查阅 TestExpectations.json 来判断某个测试结果是否符合预期。有关测试运行器的更多信息，请参阅 tools/mocha-runner。

单元测试

只测试代码（不运行浏览器）的测试放在它们所测试的类旁边， 并使用 Node 测试运行器运行（需要 Node 22+）：

npm run unit

代码审查

所有提交，包括项目成员的提交，都需要审查。我们使用 GitHub 拉取请求来实现这一点。有关使用拉取请求的更多信息，请参阅 GitHub Help。

代码风格

我们的代码风格完整定义在 eslint.config （ESLint）和 prettier.config.js （Prettier）中。

PR 的代码会自动检查，你也可以通过运行以下命令手动检查代码：

npm run lint

如果返回了一些错误，你可以尝试使用以下命令修复：

npm run format

项目结构

以下是 Puppeteer 中主要文件夹的说明：

  • packages 包含所有公共源代码。
  • test 包含所有测试源代码。
  • test-d 包含使用 tsd 的类型测试。
  • tools 包含用于构建等的各种脚本。
  • tools/mocha-runner - 包含我们测试运行器的源代码。

API 指南

在编写新的 API 方法时，请考虑以下几点：

  • 只暴露必要的最少信息。如有疑问，不要暴露新信息。
  • 优先使用方法而非 getter/setter。
    • 唯一的例外是命名空间，例如 page.keyboard 和 page.coverage
  • 所有字符串字面量必须使用小写。这包括事件名称和选项值。
  • 避免添加“糖” API（可以在用户空间中轻松实现的 API），除非它们被极其需要。

提交信息

提交信息应遵循 Conventional Commits 格式。

特别是，破坏性变更应在提交信息页脚中明确标注为“BREAKING CHANGE:”。示例：

fix(page): fix page.pizza method

This patch fixes page.pizza so that it works with iframes.

Issues: #123, #234

BREAKING CHANGE: page.pizza now delivers pizza at home by default.
To deliver to a different location, use the "deliver" option:
  `page.pizza({deliver: 'work'})`.

编写文档

文档通过 npm run docs 从 TSDoc 注释生成。合并时会自动 发布到我们的文档站点，并在发布时进行版本管理。

这意味着你不应手动修改 docs/api 文件中的 markdown。

编写 TSDoc 注释

对 Puppeteer 的每次更改都应使用 TSDoc 注释进行充分记录。关于确切的语法， 请参阅 API Extractor 文档。

  • 每个新方法都需要根据其是否属于公共 API 来添加 @public 或 @internal 标签。
  • 注释中的每一行不要超过 90 个字符（如果超过，ESLint 会警告你）。如果你是 VSCode 用户，强烈推荐 Rewrap 插件！

本地运行文档站点

  1. 在根目录下，使用 npm i --ignore-scripts 安装所有依赖。
  2. 运行 npm run docs，它将在 puppeteer/docs/api 下生成所有 .md 文件。
  3. 在 puppeteer/website 中运行 npm i。
  4. 在 puppeteer/website 中运行 npm start。

添加新依赖

对于所有依赖（包括安装依赖和开发依赖）：

  • 如果所需功能易于实现，不要添加依赖。
  • 如果添加依赖，它应该是维护良好且值得信赖的。

引入新的安装依赖的门槛尤其高：

  • 除非对项目成功至关重要，否则不要添加安装依赖。

对于与环境无关的依赖，还有其他注意事项。详情请参阅 third_party/README.md。

测试提示

  • 每个功能都应有相应的测试。
  • 每个公共 API 事件/方法都应有相应的测试。
  • 测试不应依赖外部服务。
  • 测试应在所有三个平台上工作：Mac、Linux 和 Win。这对截图测试尤其重要。

如果某个测试预期在特定配置下失败或变得不稳定，请更新 TestExpectations.json 以反映这一情况。有关 TestExpectations.json 的更多信息，请参阅 tools/mocha-runner。

API 覆盖率

每个公共 API 方法或事件在测试中至少应被调用一次。为了确保这一点， 主要的 test 命令会在测试期间运行覆盖率检查。

调试 Puppeteer

请参阅 调试提示。

通过 VSCode 调试 Puppeteer 测试

将提供的默认 .vscode/launch.template.json 复制到 .vscode/launch.json， 然后使用集成的 VSCode 调试器来调试测试。

启动前记得先构建测试，运行：

npm run build --workspace @puppeteer-test/test

面向项目维护者

升级到新的 Chrome 版本

有一个 GitHub action 每天运行一次。 该 action 有一个手动触发按钮，可以在 Actions 选项卡 上找到。

手动操作说明

你可以在本地运行 tools/update_browser_revision.mjs， 看看是否有任何更改需要提交。

注意：你可能需要运行 node --experimental-fetch tools/update_browser_revision.mjs，因为该脚本依赖 fetch

以下步骤是上述脚本的手动版本。

  1. 通过 https://googlechromelabs.github.io/chrome-for-testing/ 或 https://chromiumdash.appspot.com/ 找到合适的 Chrome revision 和 version。
  2. 用找到的 version 编号更新 packages/puppeteer-core/src/revisions.ts。
  3. 用新的 Chrome-to-Puppeteer version 映射更新 versions.json， 并用列表中的下一个版本更新 lastMaintainedChromeVersion。
  4. 运行 npm run check。如果失败，用预期的 devtools-protocol 版本更新 packages/puppeteer-core/package.json，并运行 npm install 以生成更新的 package-lock.json。
  5. 运行 npm run clean、npm install 和 npm run build。
  6. 运行 npm test 并确保所有测试通过。如果某个测试失败，请对失败的上游原因进行 二分查找，然后相应地更新测试预期（如果是预期内的更改）， 或在 Puppeteer 中绕过这些更改（如果不希望改变 Puppeteer 的可观察行为）。
  7. 提交并推送你的更改，然后打开一个拉取请求。提交信息必须包含 Chrome <version> 格式的 版本，以确保 pptr.dev 能够正确解析，例如 feat(chrome): roll to Chrome 90.0.4427.0。

二分查找上游更改

要对 Chrome/Chromium 的更改进行二分查找，请使用 https://www.chromium.org/developers/bisect-builds-py/。

python3 <path-to-chromium-checkout>/tools/bisect-builds.py -g <known-good> -b <known-bad> -cft -v --verify-range --not-interactive -c "BINARY=%p npm run test:chrome:<test-type>"

或者运行 npx puppeteer browsers bisect 中的包装器，它为 Puppeteer 测试封装了上述功能。

# From Puppeteer repo root
npx puppeteer browsers bisect -g <known-good> -b <known-bad>

发布到 npm

我们使用 release-please 来自动化发布。 当需要发布时，请在我们的 拉取请求 中 查找发布 PR 并合并它。

如果 Release Please 失败

如果 release-please 失败，需要执行以下操作：

  1. 更新本应发布的所有包的 CHANGELOG 中缺失的内容。例如，如果缺少标题， 你可能需要添加：

    • 对于 puppeteer：

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/v{PREVIOUS_VERSION}...v{NEW_VERSION}) ({CURRENT_DATE})`

    • 对于其他包：

      ## [{NEW_VERSION}](https://github.com/puppeteer/puppeteer/compare/{PACKAGE_FOLDER_NAME}-v{PREVIOUS_VERSION}...{PACKAGE_FOLDER_NAME}-v{NEW_VERSION}) ({CURRENT_DATE})

  2. 按照之前发布的惯例，为每个包创建一个 GitHub release。

Bug 分类指南

检查没有 confirmed 或 needs-feedback 标签的新提交 bug 报告：

  1. 确保该 issue 被标记为 bug 或 feature。
  2. 如果该 issue 没有清晰的重现方法，或者你无法重现，请索要重现方法并设置 needs-feedback 标签。
  3. 跟进你之前请求反馈的 issue（当用户回复时，你应该会在 GitHub 上收到通知）。
  4. 如果用户没有提供反馈，该 issue 最终会被 stale bot 关闭。
  5. 如果你能够重现该 issue，请添加 confirmed 标签。
  6. 如果 bug 出在 Chromium 侧，请创建对应的 crbug.com issue，为 GitHub issue 添加 upstream 标签，并在评论中发布 crbug.com 的链接。
  7. 如果该 issue 与 Puppeteer 或 Chromium 都无关，请关闭该 issue。
  8. 如果该 issue 是关于缺失/不正确的文档，请将其标记为 documentation。

涉及 PDF 的 issue：

  1. 如果该 issue 可以通过常规打印对话框和/或有头模式重现，请针对 Blink>Layout 组件提交 crbug.com issue。
  2. 如果该 issue 特定于无头模式，请在 crbug.com 上针对 Internals>Headless 组件提交 issue。