Puppeteer Browser.removeScreen()：Headless 多屏模拟中的虚拟屏幕移除机制

本文围绕 Puppeteer API 文档中的 Browser.removeScreen() 方法展开：它是 Puppeteer 屏幕模拟能力（与 screens()、addScreen() 配套）的移除环节，用于在 Headless 模式下删除通过 addScreen() 创建的虚拟屏幕。读完本文，你将掌握该方法的签名、参数与限制条件、底层 CDP 调用链，以及它在多屏布局、窗口最大化等自动化测试场景中的完整使用方式。

方法概览与签名

Browser.removeScreen() 用于从当前浏览器实例中移除一块已存在的屏幕。根据 API 文档（puppeteer.browser.removescreen.md），其 TypeScript 签名如下：

class Browser {
  abstract removeScreen(screenId: string): Promise<void>;
}

该方法声明在 Browser 抽象基类中（见 packages/puppeteer-core/src/api/Browser.ts），因此任何连接了 Chrome（CDP 协议）的 Browser 实例都可以调用它。

参数与返回值

参数	类型	说明
screenId	string	要移除的屏幕 ID，来源于 ScreenInfo.id 字段（通常由 addScreen() 的返回值或 screens() 的查询结果获得）

返回值： Promise<void>。移除成功后 Promise 正常解析；若传入主屏幕（primary screen）的 ID，Promise 会被拒绝（reject）。

关键限制（Remarks）

API 文档对该方法给出两条明确约束：

1. 仅在 headless 模式下受支持。在有界面（headful）模式下，screens() 返回的是宿主操作系统的真实显示器信息，这类信息不可控（Puppeteer 测试代码中直接以 Not testable in headful 跳过 headful 场景，见 test/src/browser.test.ts），因此屏幕的增删改操作只能在虚拟屏幕环境下进行。
2. 不允许移除主屏幕。如果传入的 screenId 是主屏幕（isPrimary: true）的 ID，调用会失败。这一点在 test/TestExpectations.json 的测试预期中也有对应说明：Screen methods are only supported in headless mode。

典型用法：与 addScreen / screens 配合的完整生命周期

removeScreen() 的典型工作流是“添加虚拟屏幕 → 验证屏幕数量 → 移除 → 再验证”。Puppeteer 官方测试套件中就包含一个标准用例（test/src/browser.test.ts），它清晰地展示了这段生命周期：

// 1. 在 (800, 0) 位置添加一块 1600x1200 的副屏
const screenInfo = await browser.addScreen({
  left: 800,
  top: 0,
  width: 1600,
  height: 1200,
  colorDepth: 32,
  workAreaInsets: {bottom: 80},
  label: 'secondary',
});

// 2. addScreen 返回的 ScreenInfo 会回显 isExtended: true、isPrimary: false 等字段
//    此时屏幕上共有 2 块：默认主屏 + 新建副屏
expect((await browser.screens()).length).toBe(2);

// 3. 用 addScreen 返回的 id 移除这块屏幕
await browser.removeScreen(screenInfo.id);

// 4. 移除后只剩默认主屏
expect((await browser.screens()).length).toBe(1);

几个实操要点：

• screenId 从哪来：addScreen() 返回的 ScreenInfo.id，或调用 browser.screens() 遍历结果取 id。ScreenInfo 的完整字段定义见 packages/puppeteer-core/src/api/Browser.ts，包括 left/top/width/height、availLeft/availTop/availWidth/availHeight（扣除任务栏等工作区边距后的可用区域）、devicePixelRatio、colorDepth、orientation、isExtended/isInternal/isPrimary、label 与 id。
• 移除是精确的：只有传入对应 id 的屏幕会被删除，其他虚拟屏幕与默认主屏均不受影响。
• headless 默认主屏规格：在 headless 模式下，浏览器启动后默认存在一块 800x600、colorDepth: 24、isPrimary: true 的屏幕（测试断言见 test/src/browser.test.ts），这块屏幕无法被 removeScreen() 删除。

实战场景：跨屏窗口的最大化验证

测试套件中还有一处把 addScreen / removeScreen 作为“测试夹具”使用的例子（test/src/browser.test.ts）：先添加一块副屏，把新窗口以 type: 'window' 打开并定位到副屏的可用区域内，再通过 browser.setWindowBounds(windowId, {windowState: 'maximized'}) 最大化，最后断言 windowState 为 maximized，结束时调用 removeScreen(screenInfo.id) 做清理。

这提示了 removeScreen() 的一个重要用途：为多显示器相关的 UI 行为（窗口跨屏、最大化、window.screen 属性、多屏截图等）搭建可控的测试环境，并在测试结束后还原到单屏状态，避免虚拟屏幕泄漏影响同一浏览器实例中的后续用例。

源码实现解析

CDP 实现：一次 Emulation.removeScreen 调用

在 CDP 协议实现中（packages/puppeteer-core/src/cdp/Browser.ts），该方法的实现极其直接：

override async removeScreen(screenId: string): Promise<void> {
  return await this.#connection.send('Emulation.removeScreen', {screenId});
}

也就是说，整个方法只是一次对 Chrome DevTools Protocol Emulation 域命令的转发，参数原样封装为 {screenId}。同文件中相邻的 screens()（调用 Emulation.getScreenInfos，L623-L628）和 addScreen()（调用 Emulation.addScreen，L630-L636）共同构成了 Puppeteer 对 CDP 屏幕模拟能力的完整封装。从源码结构看，Puppeteer 层本身不维护屏幕状态，所有“移除”语义都由 Chrome 浏览器内核侧完成——因此当传入主屏幕 ID 时，是内核拒绝操作并使请求失败，而不是 Puppeteer 主动拦截。

WebDriver BiDi 实现：不支持

在 BiDi 协议实现中（packages/puppeteer-core/src/bidi/Browser.ts），该方法直接抛出 UnsupportedOperation：

override addScreen(_params: AddScreenParams): Promise<ScreenInfo> {
  throw new UnsupportedOperation();
}

override removeScreen(_screenId: string): Promise<void> {
  throw new UnsupportedOperation();
}

这与 test/TestExpectations.json 中的测试预期一致：Browser.add|removeScreen should add and remove a screen 在 webDriverBiDi 参数组合下预期为 FAIL，备注为 Not supported by WebDriver BiDi。从源码结构看，BiDi 规范当前没有提供与 CDP Emulation.addScreen/removeScreen 对应的能力，因此 Puppeteer 选择了显式失败而非静默降级。

适用前提归纳：

运行条件	removeScreen() 行为
headless 模式 + CDP 协议	正常工作，移除指定虚拟屏幕
headful（有界面）模式	屏幕 API 返回真实平台屏幕信息，增删不可靠（测试预期 FAIL，备注 Not testable in headful）
WebDriver BiDi 连接	抛出 UnsupportedOperation
传入主屏幕 ID	请求失败（Promise reject）

完整可运行示例

下面是一个端到端示例，演示在 headless Chrome 中创建副屏、验证、移除的完整流程（前提：已通过 puppeteer 包启动浏览器）：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch(); // 默认 headless，CDP 协议

try {
  // 查看默认屏幕（一块 800x600 的主屏）
  const [primary] = await browser.screens();
  console.log('默认主屏:', primary.id, primary.isPrimary);

  // 添加一块位于主屏右侧的 1920x1080 副屏
  const secondary = await browser.addScreen({
    left: 800,
    top: 0,
    width: 1920,
    height: 1080,
    label: 'test-secondary',
  });
  console.log('副屏已添加, id =', secondary.id, ', isExtended =', secondary.isExtended);

  // 此时 screens() 应返回 2 块屏幕
  console.log('当前屏幕数:', (await browser.screens()).length); // 2

  // 移除副屏（只能移除扩展屏，不能移除主屏）
  await browser.removeScreen(secondary.id);
  console.log('移除后屏幕数:', (await browser.screens()).length); // 1

  // 反例：移除主屏会失败
  try {
    await browser.removeScreen(primary.id);
  } catch (err) {
    console.error('移除主屏被拒绝:', err.message);
  }
} finally {
  await browser.close();
}

关联 API 速查

removeScreen() 不是一个孤立方法，它属于 Browser 类上的一组屏幕/窗口管理 API（声明均位于 packages/puppeteer-core/src/api/Browser.ts）：

方法	作用	备注
screens(): Promise<ScreenInfo[]>	查询当前所有屏幕信息	headful 下返回真实显示器信息
addScreen(params: AddScreenParams): Promise<ScreenInfo>	添加虚拟屏幕并返回其 ScreenInfo	仅 headless；参数类型定义见 Browser.ts L315-L326
removeScreen(screenId: string): Promise<void>	按 ID 移除虚拟屏幕	仅 headless；不可移除主屏
getWindowBounds(windowId) / setWindowBounds(windowId, bounds)	查询/设置窗口位置、尺寸与最大化状态	常用于与虚拟副屏配合的跨屏窗口测试

配套的类型文档还包括 puppeteer.screeninfo.md、puppeteer.addscreenparams.md 与 puppeteer.workareainsets.md；API 索引入口见 docs/api/index.md。

小结

Browser.removeScreen() 是 Puppeteer 屏幕模拟闭环中的最后一步：addScreen() 创建虚拟屏幕并返回带 id 的 ScreenInfo，screens() 可随时核对屏幕集合，removeScreen() 则按 ID 精确移除虚拟屏幕并还原环境。理解它的三个边界——仅 headless 可用、主屏不可删除、BiDi 连接下抛出 UnsupportedOperation——就能在多显示器 UI 测试、跨屏窗口行为验证等场景中安全地使用这套 API，并借助 test/src/browser.test.ts 中的官方用例作为可复制的参考实现。