Puppeteer Page.resize() 深度指南：真实调整浏览器窗口内容区尺寸的底层实现与实战

导读

Page.resize() 是 Puppeteer 提供的一个实验性方法，用于真实调整当前页面所在浏览器窗口的物理大小，使网页内容区（content area，不含浏览器 UI 与地址栏）精确达到指定的宽高。与 Page.setViewport() 这类“仅改变渲染视口”的模拟手段不同，resize() 会触发真实的 window.onresize 事件、改变 window.innerWidth/innerHeight，适用于需要以真实窗口形态验证响应式布局、在无头浏览器中配合多屏环境测试以及研究浏览器窗口行为等场景。读完本文，你将掌握 resize() 的完整签名与语义、Chrome 端 CDP 底层调用链、Firefox/WebDriver BiDi 下的支持边界，以及如何编写可验证的调整窗口尺寸测试。

方法签名与 API 定位

Page.resize() 的官方 API 文档定义于 docs/api/puppeteer.page.resize.md，其完整签名如下：

class Page {
  abstract resize(params: {
    contentWidth: number;
    contentHeight: number;
  }): Promise<void>;
}

参数	类型	描述
params	{ contentWidth: number; contentHeight: number; }	调整后内容区（不含浏览器 UI）的宽度与高度，单位均为 CSS 像素

返回值： Promise<void> —— 窗口调整完成后 Promise 兑现，不返回具体数值。

在 Puppeteer 的类层次中，Page 是一个抽象基类（Abstract Base Class），resize() 以 abstract 形式声明，意味着真正的窗口缩放行为由各协议实现类分别完成。请特别注意源码中该方法的标注：

• 定义位置：packages/puppeteer-core/src/api/Page.ts#L3287-L3296
• JSDoc 明确说明："Resizes the browser window of this page so that the content area (excluding browser UI) has the specified width and height."
• 同时带有 @experimental 标记——这是一个实验性 API，方法签名与行为在未来版本中可能发生变化，生产代码中应谨慎依赖并留意升级公告。

语义辨析：resize 与 setViewport 的本质区别

理解 resize() 前，必须先厘清它与 setViewport() 的差异，二者是 Puppeteer 中容易混淆的一对操作：

• setViewport() 是“模拟器”：它通过 DevTools 的设备仿真（device emulation）机制覆盖页面的布局视口尺寸，不改动浏览器窗口本身的物理尺寸。网页收到的是一个“伪装的屏幕”。
• resize() 是“真实操作”：它直接改变操作系统层面浏览器窗口的物理几何尺寸，窗口变小/变大后，内容区随之伸缩，页面会触发真实的 resize 事件。

这一点在官方测试中有非常直接的印证。见 test/src/page.test.ts#L2638-L2639：

// Default view port restricts window to 800x600, so remove it.
await page.setViewport(null);

Puppeteer 默认会给页面套一个 800×600 的 viewport，若不显式 setViewport(null) 解除限制，窗口尺寸会被这个默认视口“钳制”而无法真正放大。因此，想要观察真实的窗口缩放效果，通常需要先移除默认 viewport。而 page.setViewport 自身的 API 文档见 docs/api/puppeteer.page.setviewport.md，源码注释同样写有 "page.setViewport will resize the page"，可互为参照。

Chrome 端的底层实现：一条清晰的 CDP 调用链

resize() 在 Chrome/CDP 协议下的实现非常简洁，位于 packages/puppeteer-core/src/cdp/Page.ts#L427-L437：

override async resize(params: {
  contentWidth: number;
  contentHeight: number;
}): Promise<void> {
  const windowId = await this.windowId();
  await this.#primaryTargetClient.send('Browser.setContentsSize', {
    windowId: Number(windowId),
    width: params.contentWidth,
    height: params.contentHeight,
  });
}

拆解这段代码，resize() 底层实际上完成了两次 CDP 协议交互：

1. 获取窗口 ID：调用 this.windowId()，其实现见 packages/puppeteer-core/src/cdp/Page.ts#L439-L445：

   override async windowId(): Promise<WindowId> {
     const {windowId} = await this.#primaryTargetClient.send(
       'Browser.getWindowForTarget',
     );
     return windowId.toString();
   }
   

   即通过 CDP 的 Browser.getWindowForTarget 拿到当前页面所在浏览器窗口的整数 windowId。

2. 下发窗口尺寸：以该 windowId 调用 CDP 的 Browser.setContentsSize，并将 contentWidth、contentHeight 透传为协议中的 width、height。这个协议命令的语义正是“把窗口内容区调整到指定尺寸”，与 API 文档中的描述一一对应。

值得注意的实现细节：CDP 中的 windowId 是数值类型，而 Puppeteer 的公开 Page.windowId() 返回的是字符串形式（源码中做了 windowId.toString()），因此 resize() 内部在透传前需要 Number(windowId) 再转回数值。这种“对外字符串、对内数值”的类型适配恰好说明了 Puppeteer 封装层与底层协议之间的边界。

与 Browser.setWindowBounds 的关系

如果你还需要同时控制窗口状态（如最大化、全屏、最小化）或读取窗口边界，可以配合 Browser 层的方法使用：Browser.setWindowBounds(windowId, {windowState: 'fullscreen'}) 与 Browser.getWindowBounds(windowId)，其 API 文档分别见 docs/api/puppeteer.browser.setwindowbounds.md 和 docs/api/puppeteer.browser.getwindowbounds.md。它们面向的是“窗口状态/整窗边界”层面，而 resize() 聚焦于“内容区像素尺寸”这一更细的诉求。

支持边界：Firefox 与 WebDriver BiDi 下不可用

resize() 并非所有浏览器协议下都能工作。在 WebDriver BiDi（Firefox 首选的自动化协议）实现中，该方法直接抛出异常，见 packages/puppeteer-core/src/bidi/Page.ts#L241-L250：

override resize(_params: {
  contentWidth: number;
  contentHeight: number;
}): Promise<void> {
  throw new UnsupportedOperation();
}

override async windowId(): Promise<WindowId> {
  return this.#frame.browsingContext.windowId;
}

即便 BiDi 实现可以通过 browsingContext 拿到 windowId，resize 仍以 UnsupportedOperation 明确拒绝执行。这一边界同样记录在官方测试期望文件中，test/TestExpectations.json#L776-L789 中，两个 Page.resize 相关测试在 webDriverBiDi 参数下均被标记为 FAIL，注释为 "Not supported by WebDriver BiDi"。

因此可以得出明确的兼容性结论：

运行环境	Page.resize() 行为
Chrome / Chromium（CDP）	支持，真实调整窗口内容区尺寸
Firefox（WebDriver BiDi）	抛 UnsupportedOperation，不支持

从源码结构看，这一限制根源于 WebDriver BiDi 协议本身尚未提供等价的“内容区尺寸调整”原语。若你的测试脚本需要在 Firefox 上运行，应当先用 page.browser().version() 或启动参数判断协议类型，或直接使用 Firefox 上语义接近但不等价的 setViewport() 方案，避免在 BiDi 路径上调用 resize()。

实战：编写一个可运行的窗口缩放用例

结合官方测试，一个标准的 resize() 用法如下。完整测试用例见 test/src/page.test.ts#L2628-L2656：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: false, // 真实窗口调整需在有头模式下观察
  args: ['--screen-info={3840x2160}'], // 测试中以大屏信息启动
});
const page = await browser.newPage();

// 1. 解除默认 800x600 viewport 对窗口的钳制
await page.setViewport(null);

const contentWidth = 500;
const contentHeight = 400;

// 2. 注册 onresize 监听，等待真实 resize 事件发生
const resized = page.evaluate(() => {
  return new Promise(resolve => {
    window.onresize = resolve;
  });
});

// 3. 调用 resize 并等待事件
await page.resize({contentWidth, contentHeight});
await resized;

// 4. 验证内容区尺寸真实变化
const innerSize = await page.evaluate(() => {
  return {width: window.innerWidth, height: window.innerHeight};
});
console.log(innerSize); // => {width: 500, height: 400}

await browser.close();

关于上面代码的几个关键点：

• 官方测试通过 --screen-info={3840x2160} 浏览器参数在测试环境里注入一个 4K 逻辑屏幕，确保有足够的桌面空间放大窗口；在你的本地有头环境下则无需该参数，只要操作系统屏幕不小于目标尺寸即可。
• 第 3 步 resize() 返回的 Promise 只代表“CDP 命令已下发”，不代表渲染进程已完成布局。因此官方测试会先构造一个 window.onresize 的 Promise，再 await resized 等待真实事件，最后用 window.innerWidth/innerHeight 断言验证——这是验证“真实窗口调整”与“页面视口模拟”的关键区分手法。

与全屏状态的协同处理

官方测试还覆盖了 resize 与全屏窗口状态交互的场景，见 test/src/page.test.ts#L2658-L2689：流程为「先将窗口切到 fullscreen → 再切回 normal → 然后 resize() → 断言内容区尺寸」。在类似“全屏播放后退出再固定窗口尺寸”的业务测试中，你可以沿用该组合思路：

const windowId = await page.windowId();
await browser.setWindowBounds(windowId, {windowState: 'fullscreen'});
// ... 执行全屏下的断言 ...
await browser.setWindowBounds(windowId, {windowState: 'normal'});
await page.resize({contentWidth, contentHeight});

注意事项与最佳实践

综合源码与测试，使用 Page.resize() 时建议遵循以下要点：

1. 先解除默认视口限制：直接 newPage() 后立即 resize() 可能因默认 800×600 viewport 而达不到预期宽度，先调用 page.setViewport(null)。
2. 该方法仅限 Chrome/CDP 环境：在 WebDriver BiDi（Firefox）下会抛 UnsupportedOperation，调用前应做协议判断或异常兜底。
3. 属于 @experimental API：后续 Puppeteer 版本可能调整签名或内部实现，升级依赖时注意核对 CHANGELOG（仓库根目录的 CHANGELOG.md 有完整版本记录）。
4. 配合事件等待：若需要基于新窗口尺寸做后续断言，务必先 await 页面 resize 事件（如 window.onresize）再检查 innerWidth/innerHeight，不要假定 CDP 命令返回即布局完成。
5. 窗口上限取决于真实屏幕：resize() 改变的是操作系统层面的窗口，目标尺寸受物理屏幕（或虚拟屏幕）大小限制，测试中可通过启动参数注入更大的逻辑屏幕以规避该限制。
6. 与 page.windowId() 配对理解：若需在 Browser 层进一步操作该窗口（全屏、置顶、读取边界），使用 await page.windowId() 取得窗口标识后配合 browser.setWindowBounds / browser.getWindowBounds。

小结

Page.resize() 是 Puppeteer 中少数会真实改变浏览器物理窗口的 API：它在抽象层以 contentWidth/contentHeight 描述“内容区”目标尺寸（docs/api/puppeteer.page.resize.md），在 Chrome 端通过 Browser.getWindowForTarget + Browser.setContentsSize 两条 CDP 命令完成落地（packages/puppeteer-core/src/cdp/Page.ts），在 WebDriver BiDi 端则被明确标注为不支持（packages/puppeteer-core/src/bidi/Page.ts）。无论是研究窗口与视口的边界、编写窗口尺寸相关的回归测试，还是排查响应式布局在真实窗口变化下的行为，理解这条调用链都能帮助你更精准地使用 Puppeteer 的能力。