Puppeteer Browser.newPage() 深度解析创建新标签页、独立窗口与后台页面的完整指南【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本篇围绕 Puppeteer 的Browser.newPage()方法展开它是获取Page实例最直接的入口在默认浏览器上下文default browser context中创建一个新页面。读完本文你不仅能掌握该方法的完整签名、CreatePageOptions各参数type: tab | window、windowBounds、background的用法还能从源码层面理解它在 CDP 与 BiDi 两种协议下分别如何落到Target.createTarget/browsingContext.create调用以及如何配合Page.windowId()、Browser.getWindowBounds()验证窗口行为并通过仓库内测试用例确认各项能力的实际表现。方法签名与基本行为按照官方 API 文档docs/api/puppeteer.browser.newpage.md该方法在默认浏览器上下文中创建一个新页面class Browser { abstract newPage(options?: CreatePageOptions): PromisePage; }参数类型说明optionsCreatePageOptions可选控制页面创建方式标签页/独立窗口与是否后台运行返回值PromisePage解析为创建好的 Page 实例。Browser抽象类中的定义位于 packages/puppeteer-core/src/api/Browser.ts其 JSDoc 明确写着 Creates a new page in the default browser context并给出了最小可用示例import puppeteer from puppeteer; const browser await puppeteer.launch(); const page await browser.newPage(); await page.goto(https://example.com); await browser.close();需要注意一个隐含前提newPage()创建的是默认上下文里的页面。默认上下文共享 Cookie、缓存与权限状态且不能被关闭见 Browser.defaultBrowserContext 文档The default browser context cannot be closed.。如果你需要隔离的环境应改用browser.createBrowserContext()后再调用context.newPage()两者的options类型相同实现见 BrowserContext.newPage 文档。CreatePageOptions 参数详解CreatePageOptions是Browser与BrowserContext共用的选项类型在源码中的定义见 packages/puppeteer-core/src/api/Browser.ts#L255-L270类型文档docs/api/puppeteer.createpageoptions.mdexport type CreatePageOptions ( | { type?: tab; } | { type: window; windowBounds?: WindowBounds; } ) { /** * Whether to create the page in the background. * defaultValue false */ background?: boolean; };这是一个联合类型与{ background?: boolean }的交叉实际含义如下type: tab默认不传options或传{type: tab}时行为一致在当前浏览器窗口的标签栏中新开一个标签页。这是最常见、也是性能开销最小的用法——共享同一窗口、同一 GPU 进程与渲染资源适合绝大多数爬取、截图、多任务并行的场景。type: windowwindowBounds传{type: window}会强制新页面在独立窗口中打开并可通过windowBounds指定窗口的几何位置、尺寸与窗口状态。WindowBounds接口定义在 packages/puppeteer-core/src/api/Browser.ts#L236-L245所有字段均为可选接口文档docs/api/puppeteer.windowbounds.md字段类型含义leftnumber窗口左上角的 X 坐标topnumber窗口左上角的 Y 坐标widthnumber窗口宽度heightnumber窗口高度windowStateWindowState窗口状态WindowState的取值为源码 api/Browser.ts#L231-L234export type WindowState normal | minimized | maximized | fullscreen;典型用法——在指定位置打开一个 750×550 的独立窗口const page await browser.newPage({ type: window, windowBounds: {left: 50, top: 50, width: 750, height: 550}, });或者只指定窗口状态// 以最大化状态打开新窗口 const page await browser.newPage({ type: window, windowBounds: {windowState: maximized}, });backgroundbackground与type正交可以叠加使用。设为true时新页面以后台方式创建页面不会获得焦点document.visibilityState为hidden适合在后台静默运行任务如预热页面、批量抓取避免抢占用户当前焦点。const page await browser.newPage({background: true}); // page.evaluate(() document.visibilityState) hidden源码实现CDP 协议下的调用链newPage()在 CDP 协议下的实现位于CdpBrowser其核心是一条清晰的委托链CdpBrowser.newPage()转发到默认上下文packages/puppeteer-core/src/cdp/Browser.ts#L410-L412override async newPage(options?: CreatePageOptions): PromisePage { return await this.#defaultContext.newPage(options); }CdpBrowserContext.newPage()加锁后调用_createPageInContextpackages/puppeteer-core/src/cdp/BrowserContext.ts#L132-L135override async newPage(options?: CreatePageOptions): PromisePage { using _guard await this.waitForScreenshotOperations(); return await this.#browser._createPageInContext(this.#id, options); }这里的#id对默认上下文为undefined因此browser.newPage()与browser.defaultBrowserContext().newPage()最终走的是同一条路径。waitForScreenshotOperations()则保证创建页面前该上下文上已挂起的截屏操作完成避免并发冲突。_createPageInContext()是真正发协议的地方packages/puppeteer-core/src/cdp/Browser.ts#L414-L455const hasTargets this.targets().filter(t { return t.browserContext().id contextId; }).length 0; const windowBounds options?.type window ? options.windowBounds : undefined; const {targetId} await this.#connection.send(Target.createTarget, { url: about:blank, browserContextId: contextId || undefined, left: windowBounds?.left, top: windowBounds?.top, width: windowBounds?.width, height: windowBounds?.height, windowState: windowBounds?.windowState, // Works around crbug.com/454825274. newWindow: hasTargets options?.type window ? true : undefined, background: options?.background, });从源码结构看可以提取出几个关键实现事实新页面初始 URL 固定为about:blank后续由你自己goto或setContentwindowBounds只有在type window时才会生效——源码中windowBounds变量的赋值就带了这个条件判断若你传了type: tab同时带了windowBounds它会被静默忽略类型系统上也不会允许因为tab分支没有windowBounds字段newWindow参数是一个 Chromium bug 的规避仅当上下文中已存在其他 target 且请求新建窗口时才置true源码注释标注 Works around crbug.com/454825274background直接透传给Target.createTarget由浏览器侧处理后台标签的可见性状态。拿到targetId后实现并不立即返回而是用browser.waitForTarget(t t._targetId targetId)等待对应的Target对象被 TargetManager 注册再检查target._initializedDeferred是否为SUCCESS初始化失败会抛出Failed to create target for page (id ...)最后通过target.page()取出包装好的Page对象返回。也就是说newPage()resolve 时页面 target 已经完成初始化你可以直接在上面执行goto、evaluate等操作。BiDi 协议下的实现差异Puppeteer 同时支持 WebDriver BiDi 协议相关背景见 docs/webdriver-bidi.md其实现位于 packages/puppeteer-core/src/bidi/BrowserContext.ts#L206-L242const type options?.type window ? Bidi.BrowsingContext.CreateType.Window : Bidi.BrowsingContext.CreateType.Tab; const context await this.userContext.createBrowsingContext(type, { background: options?.background, }); ... if (options?.type window options?.windowBounds ! undefined) { try { await this.browser().setWindowBounds( context.windowId, options.windowBounds, ); } catch (error) { // Tolerate not supporting browser.setClientWindowState. Only log it. this.#logger?.(DEBUG_PREFIXES.error)?.(error); } }与 CDP 实现的差异值得注意type映射到 BiDi 的BrowsingContext.CreateTypeWindow/Tabbackground同样透传windowBounds采用先创建、后调整的两步策略先创建窗口再调用browser.setWindowBounds(context.windowId, windowBounds)调整。这与 CDP 中把left/top/width/height/windowState一次性塞进Target.createTarget的做法不同若浏览器不支持browser.setClientWindowState能力异常会被捕获并只记录日志而不中断创建流程Tolerate not supporting即 BiDi 下windowBounds属于尽力而为若 launch 时配置了defaultViewportBiDi 实现还会对新页面补一次page.setViewport(this.#defaultViewport)。这意味着在 BiDi 模式下windowBounds相关能力对具体浏览器实现存在兼容性前提使用建议以 CDPChrome为主。实战创建、验证与窗口控制通过 windowId 验证窗口几何创建独立窗口后可用Page.windowId()拿到所属窗口 ID再用Browser.getWindowBounds()验证几何是否生效windowId()实现见 packages/puppeteer-core/src/cdp/Page.ts#L439-L445内部调用Browser.getWindowForTargetgetWindowBounds/setWindowBounds实现见 cdp/Browser.ts#L642-L657import puppeteer from puppeteer; const browser await puppeteer.launch(); const initialBounds {left: 10, top: 20, width: 800, height: 600}; const page await browser.newPage({ type: window, windowBounds: initialBounds, }); const windowId await page.windowId(); const actual await browser.getWindowBounds(windowId); console.log(actual); // {left: 10, top: 20, width: 800, height: 600, ...} // 后续还可动态调整窗口位置/尺寸 await browser.setWindowBounds(windowId, {left: 200, top: 200, width: 1024, height: 768}); await page.close(); await browser.close();仓库测试 test/src/browser.test.ts 中的用例正是这个模式创建带windowBounds的窗口页后断言getWindowBounds返回的对象与初始值一致另一个用例先通过browser.addScreen()添加第二块屏幕再把新窗口开到副屏上left: screenInfo.availLeft 50, ...演示了newPage的多屏窗口布局能力。后台页面与可见性test/src/page.test.ts 的 should create a background page 用例验证了background: true的语义const page await context.newPage({background: true}); expect( await page.evaluate(() { return document.visibilityState; }), ).toBe(hidden);即后台页面的document.visibilityState为hidden——如果你依赖requestAnimationFrame或IntersectionObserver的可见性触发逻辑后台页面中这些 API 的行为需要留意。多窗口并发示例const browser await puppeteer.launch({headless: false}); // 标签页 1共享窗口 const tab1 await browser.newPage(); // 独立窗口 2固定位置与尺寸 const win2 await browser.newPage({ type: window, windowBounds: {left: 400, top: 100, width: 1200, height: 800}, }); // 后台窗口 3不抢焦点 const bg await browser.newPage({type: window, background: true}); const pages await browser.pages(); console.log(pages.length); // 3browser.pages()会聚合所有上下文中的页面api/Browser.ts#L637-L647可用于确认新建页面已登记注意非可见页面如background_page类型的 target不会出现在列表中。行为验证仓库测试用例覆盖以下测试用例均可在仓库中直接找到为上述行为提供了验证依据新窗口包含检查test/src/page.test.ts#L38-L48context.newPage({type: window})后context.pages()与browser.pages()都应包含该页面指定位置与尺寸test/src/page.test.ts#L49-L66windowBounds: {left: 50, top: 50, width: 750, height: 550}后通过window.outerWidth/outerHeight断言外框尺寸精确为 750×550证明 bounds 作用于窗口外框而非视口最大化状态test/src/page.test.ts#L67-L85windowState: maximized下窗口外框尺寸等于 headless 默认屏幕的 800×600getWindowBounds回读test/src/browser.test.ts创建带 bounds 的窗口后browser.getWindowBounds(page.windowId())与传入值toMatchObject相等。与 BrowserContext.newPage() 的关系及 API 索引browser.newPage(options)本质上等价于browser.defaultBrowserContext().newPage(options)——从 CDP 实现看二者汇聚到同一个_createPageInContext(contextId, options)仅contextId不同默认上下文为undefined。两者的取舍场景推荐入口简单脚本、所有页面共享状态browser.newPage()需要隔离 Cookie/缓存/权限多用户、多站点browser.createBrowserContext()→context.newPage()创建纯净环境后释放非默认上下文支持context.close()默认上下文不可关闭相关 API 文档索引均以仓库根目录为基准CreatePageOptions 类型WindowBounds 接口Page 类Browser.defaultBrowserContextBrowserContext.newPageBrowser.getWindowBounds / Browser.setWindowBoundsPage.windowId小结Browser.newPage()虽只有一个可选参数但背后覆盖了三类创建语义默认标签页type: tab、可精确控制位置/尺寸/窗口状态的独立窗口type: windowwindowBounds、以及不抢焦点的后台页面background: true。CDP 实现通过一次Target.createTarget含newWindow的 bug workaround加waitForTarget初始化等待完成创建BiDi 实现则采用创建后 setWindowBounds的两步策略并容忍能力缺失。日常使用记住三点即可初始 URL 恒为about:blankwindowBounds仅对type: window生效且作用于窗口外框隔离需求请走BrowserContext.newPage()而非叠加默认上下文页面。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考