Puppeteer 的 Extension 类解析：驱动与管理已安装浏览器扩展的官方 API

Puppeteer 的 Extension 类抽象了「已安装到浏览器中的扩展（extension）」，它既能读取扩展的 ID、名称、版本、磁盘路径与启用状态，又能与该扩展的后台 Service Worker、页面进行交互，还能通过 triggerAction() 模拟用户点击浏览器工具栏上的扩展图标。本文以 docs/api/puppeteer.extension.md 为核心，结合仓库源码，完整讲解该类的属性、方法、在 Browser 上的获取/安装/卸载工作流，以及基于当前仓库源码可确认的实现细节与使用限制。

Extension 类概览：一个浏览器扩展的句柄

Extension 是一个抽象基类（abstract class），它的类型签名如下：

export declare abstract class Extension

在 packages/puppeteer-core/src/api/Extension.ts 中可以确认其真实定义：它是一个被标记为 @public 但同时标记为 @experimental（实验性） 的抽象类。这意味着该 API 面向公共使用，但其行为与签名仍可能在后续版本中调整，在依赖它编写长期稳定的自动化脚本前需要留意这一点。

官方文档对该类的定位描述是：

Extension represents a browser extension installed in the browser. It provides access to the extension's ID, name, and version, as well as methods for interacting with the extension's background workers and pages.

即它代表「一个已安装到浏览器中的扩展」，既负责暴露扩展的基本元数据，也负责提供与该扩展的后台（background）工作线程和页面进行交互的能力。

构造器是内部的：请勿直接 new

该类的构造函数在文档中被标记为 internal，源码中的实现也证实了这一点：

constructor(id: string, version: string, name: string, path: string, enabled: boolean) {
  if (!id || !version) {
    throw new Error('Extension ID and version are required');
  }
  // ...赋值给私有字段
}

两个值得注意的细节：

1. 第三方代码不应直接调用构造函数，也不应创建继承 Extension 的 class 子类。实际使用中，你只会从 browser.extensions() 等方法拿到已构造好的实例；
2. 构造函数在创建时会强校验 id 与 version 非空，否则直接抛出 Extension ID and version are required。这从源码层面印证了「ID 与版本号是扩展身份的必要组成部分」这一设计。

由于 25.8.0 文档目录并未单独存在于仓库中（当前版本化文档由 docs/api/ 生成），本文统一引用 docs/api 下的文档作为权威来源。

五大只读属性：扩展的元数据视图

Extension 类对外只暴露只读（readonly） 属性，不允许在运行时篡改扩展元数据。下表完整罗列文档定义的属性：

属性	修饰符	类型	说明
enabled	readonly	boolean	该扩展当前是否处于启用状态
id	readonly	string	扩展的唯一标识符
name	readonly	string	扩展在 manifest 中声明的名称
path	readonly	string	扩展在文件系统中所在的位置路径
version	readonly	string	扩展在 manifest 中声明的版本号

在 源码 中，每个属性都是一个返回私有字段的 getter，例如：

• get id() 返回扩展的唯一标识符；
• get name() / get version() 均以扩展自身的 manifest.json 为准；
• get path() 对应扩展在磁盘上被加载的位置；
• get enabled() 对应扩展的启用状态。

理解这些元数据的最典型场景是：程序化安装多个扩展后，用它们的 ID/名称去做去重、匹配或日志输出。文档给出的示例正是遍历全部分机扩展：

const extensions = await browser.extensions();
for (const [id, extension] of extensions) {
  console.log(extension.name, id);
}

注意这里 browser.extensions() 返回的是 Promise<Map<string, Extension>>，Map 的 key 是扩展 ID，value 是 Extension 实例，因此遍历时解构出的第一个元素天然就是扩展 ID，与 extension.id 保持一致。

三个核心方法：页面、后台 Worker 与触发动作

除了元数据，Extension 还提供三个抽象方法，分别对应交互式测试中最高频的三个诉求。

workers()：获取扩展的活动 Service Worker

class Extension {
  abstract workers(): Promise<WebWorker[]>;
}

返回： Promise<WebWorker[]>（WebWorker 详见 puppeteer.webworker.md）

它返回当前归属于该扩展的活动 Service Worker（service workers）列表。在现代 Manifest V3（MV3）扩展架构下，扩展的后台逻辑以 Service Worker 承载，所以 workers() 是拿到「扩展后台运行时」的入口。拿到 WebWorker 后，你便可以使用 WebWorker.evaluate() 等能力在扩展的后台上下文里执行脚本、校验状态。

pages()：获取扩展的活动可见页面

class Extension {
  abstract pages(): Promise<Page[]>;
}

返回： Promise<Page[]>（Page 详见 puppeteer.page.md）

它返回该扩展当前处于活动且可见状态的页面。这类页面通常包括扩展弹出的 popup 页面、options/设置页，或扩展自己打开的标签页。返回的每个元素都是标准的 Page 对象，因此可以直接调用 Page.evaluate()、截图、waitForSelector 等全套页面级 API，实现对扩展 UI 的端到端验证。

triggerAction(page)：模拟点击扩展的工具栏图标

class Extension {
  abstract triggerAction(page: Page): Promise<void>;
}

参数： page: Page——要对其触发动作的页面。

返回： Promise<void>

这是三个方法中最「行为化」的一个：它触发该扩展针对指定页面 page 的默认动作（default action），语义上等价于用户点击浏览器工具栏上的扩展图标。根据文档的精确描述，其典型后果有两种：

• 打开一个 popup 弹窗（随后可通过 pages() 拿到并操作它）；
• 执行一段动作脚本（action script）。

换句话说，triggerAction() 把「用户手动点一下扩展图标」这个行为自动化，是模拟真实用户与扩展交互的核心 API。通常的使用顺序是：先 installExtension() 安装 → 用 page.goto() 打开目标站点 → extension.triggerAction(page) 唤起扩展动作 → 再用 extension.pages() 定位弹窗并继续断言。

与 Browser 协作的完整生命周期：安装、枚举与卸载

Extension 实例的来源是 Browser 对象。仓库中 packages/puppeteer-core/src/api/Browser.ts 与 docs/api 文档共同定义了三个配套方法，构成扩展管理的完整闭环：

1. 安装：browser.installExtension(path, options?)

abstract installExtension(
  path: string,
  options?: ExtensionInstallOptions,
): Promise<string>;

• path：扩展目录（内含 manifest.json 的文件夹）路径；
• options：可选参数，类型为 ExtensionInstallOptions；
• 返回：安装成功后返回该扩展的 ID（字符串）。

ExtensionInstallOptions 目前只有一个可选字段：

属性	类型	说明
enabledInIncognito	boolean	是否在 Chrome 的无痕 / OTR（Off-The-Record）配置文件中启用该扩展

这个字段服务于「把扩展同时用于普通会话与无痕会话」的自动化场景。

2. 枚举：browser.extensions()

abstract extensions(): Promise<Map<string, Extension>>;

检索浏览器中已安装的全部扩展，返回 key 为扩展 ID、value 为 Extension 实例的 Map。这是拿到 Extension 实例的规范入口（前文的示例代码即基于此方法）。

3. 卸载：browser.uninstallExtension(id)

abstract uninstallExtension(id: string): Promise<void>;

按扩展 ID 将其从浏览器中卸载，用于清理测试环境、避免扩展间的相互干扰。

综合示例：驱动一个扩展的完整测试流程

把以上 API 串起来，一个典型的「加载扩展并与之交互」的脚本骨架如下：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({headless: true});

// 1. 安装本地打包好的扩展（含 manifest.json 的目录）
const extensionId = await browser.installExtension('./dist/my-extension', {
  enabledInIncognito: false,
});
console.log('installed id:', extensionId);

// 2. 从已安装扩展中取出 Extension 句柄
const extensions = await browser.extensions();
const extension = extensions.get(extensionId);
if (!extension) {
  throw new Error('extension not found');
}
console.log(extension.name, extension.version, extension.enabled, extension.path);

// 3. 在目标页面上触发扩展动作（等价于点击工具栏图标）
const page = await browser.newPage();
await page.goto('https://example.com');
await extension.triggerAction(page);

// 4. 读取扩展弹出的页面 / 后台 worker 并做断言
for (const extPage of await extension.pages()) {
  console.log(await extPage.title());
}
for (const worker of await extension.workers()) {
  console.log(worker.url());
}

await browser.close();

说明：browser.installExtension、extensions、uninstallExtension 均为 Browser 的抽象方法，实际能力由具体浏览器实现（当前仓库中对应 CDP/Chromium 实现位于 packages/puppeteer-core/src/cdp/）提供；installExtension 的 enabledInIncognito 选项描述中明确指向 Chrome，说明该能力是面向 Chrome/Chromium 的。

源码视角：从抽象 API 到实现细节

从仓库源码可以进一步确认如下实现事实（可作为引用该 API 时的依据）：

• Extension 抽象类定义于 packages/puppeteer-core/src/api/Extension.ts，@public 且 @experimental；所有元数据字段以私有字段存储、以 getter 暴露，禁止外部直接修改；
• 构造函数强制要求 id 与 version 至少非空（Extension.ts 中构造器抛错逻辑）；
• workers()、pages()、triggerAction() 均声明为抽象方法，具体行为由平台子类实现；文档层面三者分别对应 puppeteer.extension.workers.md、puppeteer.extension.pages.md、puppeteer.extension.triggeraction.md；
• Browser 侧配套的 installExtension / uninstallExtension / extensions 抽象签名集中在 packages/puppeteer-core/src/api/Browser.ts，签名与文档一一对应；
• 仓库在 examples/puppeteer-in-extension/ 目录下还提供了一套「在浏览器扩展内部使用 Puppeteer」的完整示例（含 manifest.json、background.js、iframe.html、playground.html 与 rollup 构建配置），是探索 Puppeteer 与浏览器扩展生态结合方向的另一份可运行参考。

使用限制与注意事项

基于文档措辞与源码标记，使用本 API 时应注意以下几点，避免踩坑：

1. 实验性 API：Extension 在源码中被标注为 @experimental，接口可能在后续 minor 版本中调整，请留意 CHANGELOG 与版本升级说明；
2. 不要实例化与继承：构造器被标记 internal，第三方只能消费从 browser.extensions() 等入口获得的实例；自行 new Extension(...) 或继承都会违背 API 契约；
3. 属性语义来自 manifest：name、version 均以扩展 manifest.json 的声明为准，不要假设它们与目录名或 ID 一致；
4. pages() 的语义范围：它返回的是该扩展当前活动且可见的页面（如 popup、options 页），并非扩展文件里声明的所有页面；没有弹出时得到的是空列表属于正常现象；
5. 平台差异：与扩展安装/触发相关的能力及 enabledInIncognito 选项在文档中与 Chrome 绑定，面向 Firefox 时需以你实际运行的浏览器所支持的 API 为准；
6. 权限与流程依赖：triggerAction(page) 的行为取决于扩展在 manifest.json 中声明的 default action（action/browser_action）配置，若扩展没有声明动作图标，触发结果可能为空操作——这与真实浏览器行为一致。

结语

Extension 类把浏览器扩展从「黑盒外挂」变成了一等公民的可编程对象：通过五个只读属性读取扩展元数据，通过 workers() 与 pages() 深入扩展内部运行时，通过 triggerAction() 还原真实用户的点击行为，再配合 Browser 上的 installExtension / extensions / uninstallExtension 完成全生命周期管理。理解它的抽象边界（不可构造、只读元数据、experimental）与文档/源码契约，就能在基于 Puppeteer 的 E2E 测试与自动化任务中可靠地驾驭真实浏览器扩展。