Puppeteer `Extension.pages()` 详解：枚举并操控浏览器扩展的可见页面

Puppeteer 在 Chrome 扩展自动化场景中提供了 Extension 抽象类，其中 pages() 方法用于返回某个已安装扩展当前处于激活且可见状态的所有页面（API 文档）。本文将以其为骨架，结合浏览器上下文（browser.extensions()、Extension.workers()、triggerAction()）与 CDP 层实现，说明如何在测试与端到端自动化中获取、校验并操作扩展页面（如 popup、options 页），并附带可运行的完整示例。

方法签名与返回类型

Extension.pages() 在 Extension 抽象类 中声明为：

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

返回类型： Promise<Page[]>，即一批 Page 实例数组。

语义上，该方法返回“当前属于该扩展、且处于激活与可见状态”的页面。所谓“页面”通常是扩展打开的标签页、popup 弹窗或 options/设置页等以 chrome-extension:// 为协议 URL 的文档窗口。

完整上下文：Extension 对象从哪里来

pages() 是 Extension 实例方法，因此第一步是获取目标扩展的 Extension 对象。典型路径：

1. 调用 Browser.installExtension() 安装扩展并取得扩展 ID；
2. 调用 Browser.extensions() 获取 Map<string, Extension>，键为扩展 ID，值为对应的 Extension 实例；
3. 对该实例调用 pages()。

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  channel: 'chrome',
  headless: false, // 扩展自动化需要新的 headless 模式
});

// 安装本地打包好的 .crx 或未打包扩展目录
const extensionId = await browser.installExtension('/path/to/extension');

// 取得 Extension 对象
const extension = (await browser.extensions()).get(extensionId)!;

// 枚举该扩展当前激活且可见的所有页面
const pages = await extension.pages();
for (const page of pages) {
  console.log(page.url()); // 形如 chrome-extension://<id>/popup.html
}

await browser.close();

Extension 类 除 pages() 外还提供只读属性 id、name、version、path、enabled，便于在操作前确认扩展身份。例如遍历所有扩展并打印名称：

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

底层原理：CDP 实现如何筛选扩展页面

从源码结构看，Extension 是抽象基类（packages/puppeteer-core/src/api/Extension.ts），其构造函数被标记为 internal，第三方代码不能直接构造或继承。面向 CDP 协议的实际实现为 CdpExtension（packages/puppeteer-core/src/cdp/Extension.ts），在 cdp/Browser.ts 中随 target 发现被实例化。

pages() 的实现逻辑分三步：

async pages(): Promise<Page[]> {
  const targets = this.#browser.targets();

  const extensionPages = targets.filter((target: Target) => {
    const targetUrl = target.url();
    return (
      (target.type() === 'page' || target.type() === 'background_page') &&
      targetUrl.startsWith('chrome-extension://' + this.id)
    );
  });

  const pages = await Promise.all(
    extensionPages.map(async target => {
      try {
        return await target.asPage();
      } catch (err) {
        if (this.#canIgnoreError(err)) {
          this.#logger?.(DEBUG_PREFIXES.error)?.(err);
          return null;
        }
        throw err;
      }
    }),
  );

  return pages.filter((page): page is Page => page !== null);
}

关键点：

• target 类型过滤：只保留 target.type() === 'page' 或 'background_page' 的 target。popup、扩展打开的标签页通常是 page 类型，而 Manifest V2 时代常见的后台页为 background_page 类型；
• URL 前缀过滤：通过 targetUrl.startsWith('chrome-extension://' + this.id) 确保只返回属于该扩展 ID 的页面，避免与其他扩展、普通网页 target 混淆；
• 可见性语义：能出现在 browser.targets() 中、可被 asPage() 成功包装的 target，从实现看即为“激活且可见”；反之已关闭、被丢弃的页面不会进入返回数组；
• 容错处理：单个 target 因“已关闭”或“找不到对应 target id”而转换失败时，会被记录日志并过滤掉（#canIgnoreError），其余错误仍会向上抛出。

相应地，该方法天然会排除该扩展的 service worker——后者由 Extension.workers()（见 docs/api/puppeteer.extension.workers.md）负责枚举，其过滤条件是 type === 'service_worker' 且 URL 以 chrome-extension://<id> 开头，二者形成互补：一个管“页面”，一个管“后台 Worker”。

端到端流程：从安装扩展到列出 popup 页面

pages() 最常见的应用是在自动化流程中校验扩展 UI。仓库测试 test/src/cdp/extensions.test.ts（"should list extension pages"）完整演示了推荐用法：

const extensionId = await browser.installExtension(extensionWithPagePath);
const extension = (await browser.extensions()).get(extensionId);

const page = await browser.newPage();
await page.goto(server.EMPTY_PAGE);

// 模拟用户在工具栏点击扩展图标，触发 action 并打开 popup
await extension?.triggerAction(page);

// 等待 popup 对应的 target 出现
await browser.waitForTarget(target => {
  return (
    target.url().includes('popup.html') &&
    target.url().includes(extensionId)
  );
});

// 现在扩展拥有一个激活且可见的 popup 页面
const pages = await extension!.pages();
expect(pages.length).toBeGreaterThanOrEqual(1);
expect(
  pages.some(p => p.url().includes('popup.html')),
).toBe(true);

该测试揭示了一个重要的时序事实：若扩展只在点击 action 后才弹出 popup，那么在 triggerAction(page) 之前调用 pages() 很可能得到空数组。因此实践中应先用 browser.waitForTarget()（或 page.waitForTarget）等待 popup target 被创建，再调用 pages() 收集页面对象。测试中亦通过 uninstallExtension(extensionId) 收尾，验证卸载后不会再有该扩展的 target 残留（见同文件 assertNoServiceWorkerReported 辅助逻辑）。

拿到扩展页面后能做什么

返回的每个 Page 与普通网页的 Page 完全一致，可直接复用 Puppeteer 的页面 API 进行验证与交互：

const popupPage = pages.find(p => p.url().includes('popup.html'));
if (popupPage) {
  // 等待 popup 内 UI 渲染完成
  await popupPage.waitForSelector('#submit-button');
  // 读取 popup 内容文本
  const text = await popupPage.$eval('body', el => el.innerText);
  // 甚至可以驱动 popup 内元素交互
  await popupPage.click('#submit-button');
}

同时也可以借助 page.on('console') 之类的事件监听扩展页面的运行日志——同目录测试 "should capture console logs from extension pages"（test/src/cdp/extensions.test.ts）即是先 triggerExtensionAction 打开扩展页面，再断言其 console 输出的范例。

在操作前触发扩展动作

如需让扩展的 popup 或 action 页面现形，两种等价方式：

// 方式一：经由 Extension.triggerAction(page)
await extension.triggerAction(page);

// 方式二：经由 Page 侧方法（内部同样发送 Extensions.triggerAction）
await page.triggerExtensionAction(extension);

triggerAction 底层通过 CDP 的 Extensions.triggerAction 命令，携带 { id: extensionId, targetId: page._tabId }，等价于模拟用户在工具栏点击扩展图标（见 docs/api/puppeteer.extension.triggeraction.md）。注意：只有用户显式触发 action，popup 才会打开，单纯安装扩展不一定产生可见页面。

完整可运行示例

将上述要点串联成一个自包含脚本：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  channel: 'chrome',
  headless: false, // 扩展自动化需要新的 headless 模式
});

try {
  const extensionId = await browser.installExtension(
    '/path/to/unpacked/extension',
  );
  const extension = (await browser.extensions()).get(extensionId);
  if (!extension) {
    throw new Error(`Extension ${extensionId} not found`);
  }

  // 打开一个普通页面作为触发 action 的上下文
  const page = await browser.newPage();
  await page.goto('https://example.com');

  // 触发扩展工具栏动作（popup 此时才会出现）
  await extension.triggerAction(page);

  // 等待 popup target 出现
  await browser.waitForTarget(target => {
    return (
      target.url().includes('popup.html') &&
      target.url().includes(extensionId)
    );
  });

  // 枚举扩展当前激活且可见的页面
  const pages = await extension.pages();
  console.log(`Extension "${extension.name}" has ${pages.length} visible page(s)`);
  for (const p of pages) {
    console.log('-', p.url());
  }
} finally {
  await browser.close();
}

已知注意点

• Extension 的构造函数为 internal，请勿自行 new Extension(...) 或继承（见 docs/api/puppeteer.extension.md 的 Remarks）；
• pages() 返回的是调用瞬间的快照。popup 关闭、页面被垃圾回收后再次调用，结果会相应变化，需要时请重新查询；
• 该方法依赖 Chrome 的扩展 target 管理，属于实验性能力（源码中标记 @experimental，见 Extension.ts），行为可能随 Chrome 与 Puppeteer 版本演进调整；
• 若要编写自己的扩展做自动化对象，仓库提供参考示例 examples/puppeteer-in-extension；更系统的扩展用法可参考指南 docs/guides/chrome-extensions.md。

总结

Extension.pages() 是 Puppeteer 扩展自动化中“读取扩展可见页面”的权威入口：在 browser.extensions() 拿到 Extension 后，配合 triggerAction(page) 与 browser.waitForTarget()，即可可靠地让扩展 popup/options 页面出现并将其包装为标准的 Page 对象，从而复用 Puppeteer 全部页面级 API 完成断言与交互。其底层实现在 packages/puppeteer-core/src/cdp/Extension.ts 中通过 target 类型（page/background_page）与 chrome-extension:// URL 前缀双重过滤完成归属判定，行为已被 test/src/cdp/extensions.test.ts 中的端到端用例覆盖验证。