Puppeteer Browser.cookies() 详解获取默认浏览器上下文完整 Cookie 列表的机制与实战【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteerBrowser.cookies()是 Puppeteer 中在浏览器级别读取 Cookie 的核心 API它以一次调用返回默认BrowserContext中所有页面的全部 Cookie是登录态检查、请求调试、状态序列化等场景的常用入口。本文以Browser.cookies()文档为骨架结合当前仓库的源码实现与测试用例讲清它的签名、返回结构、底层 CDP 调用链以及它与BrowserContext.cookies()的等价关系读完后可直接在生产脚本中正确使用并排查 Cookie 读取问题。方法概述与签名Browser.cookies()方法用于返回默认 BrowserContext 中的所有 CookieReturns all cookies in the default BrowserContext。原始 API 文档位于 docs/api/puppeteer.browser.cookies.md其定义如下Signatureclass Browser { cookies(): PromiseCookie[]; }Returns:PromiseCookie[]—— 返回一个 Promise解析结果为 Cookie 对象数组。Remarks文档原注官方文档对它的定位是一句话Shortcut forbrowser.defaultBrowserContext().cookies()即它只是默认浏览器上下文cookies()方法的快捷方式。这意味着它只能读取默认上下文的 Cookie通过browser.createBrowserContext()创建的其它隔离/无痕上下文中的 Cookie需要直接调用对应上下文实例的BrowserContext.cookies()见 docs/api/puppeteer.browsercontext.cookies.md默认上下文不能被关闭源码中对close()有assert(this.#id, Default BrowserContext cannot be closed!)的断言见下文实现分析因此browser.cookies()永远有稳定的读取入口。这一快捷方式的定位在源码中得到逐字印证// packages/puppeteer-core/src/api/Browser.ts async cookies(): PromiseCookie[] { return await this.defaultBrowserContext().cookies(); }参见 api/Browser.ts#L689-L692。调用链完全等价于defaultBrowserContext()→BrowserContext.cookies()没有任何额外的过滤或状态缓存逻辑。返回值Cookie 接口的完整字段browser.cookies()返回的每个元素都是 Cookie 接口对象其定义为interface Cookie extends CookieData见 common/Cookie.ts#L59-L85。CookieData提供name、value、domain、path、httpOnly、secure、sameSite、partitionKey等写入与读取通用的基础字段Cookie在此基础上补充了五个由浏览器回传、只读性质的字段完整字段表如下继承自 docs/api/puppeteer.cookie.md属性修饰符类型说明path—stringCookie path.Cookie 路径expires—numberCookie 过期时间UNIX 纪元起的秒数会话 Cookie 为-1secure—boolean是否为 Secure Cookie仅 HTTPS 传输session—boolean是否为会话 Cookiesize—numberCookie 大小partitionKeyOpaqueoptionalbooleanCookie 分区键是否不透明。仅 Chrome 支持几个字段在自动化实践中值得特别注意expires与session的对应关系expires -1的 Cookie 即会话 Cookiesession为true。这也是 Puppeteer 删除 Cookie 的原理——BrowserContext.deleteCookie()内部就是把目标 Cookie 的expires改写为1一个过去的时间点再写回从而让浏览器立即将其过期见 api/BrowserContext.ts#L299-L308。因此browser.cookies()读到的过期时间可以直接用于判断该 Cookie 是否随会话消失。partitionKeyOpaque仅 Chrome 支持它对应 Chrome 第三方 Cookie 分区CHIPS机制中的不透明分区键。同文件中的 CookiePartitionKey 定义了sourceOrigin与可选的hasCrossSiteAncestor两个字段用于描述 Cookie 分区归属。sameSite/priority/sourceScheme等枚举类型CookieSameSiteStrict | Lax | None | Default、CookiePriorityLow | Medium | High、CookieSourceSchemeUnset | NonSecure | Secure均在 common/Cookie.ts#L13-L30 中定义可用于断言服务端下发的 Cookie 策略是否符合预期。底层实现CDP 调用链与数据转换Browser.cookies()本身只是一层转发真正干活的是其所在实现的BrowserContext子类。CDPChrome DevTools Protocol实现中cookies()直接下发Storage.getCookies命令并把返回的partitionKey从 CDP 结构转换为 Puppeteer 结构// packages/puppeteer-core/src/cdp/BrowserContext.ts override async cookies(): PromiseCookie[] { const {cookies} await this.#connection.send(Storage.getCookies, { browserContextId: this.#id, }); return cookies.map(cookie { return { ...cookie, partitionKey: cookie.partitionKey ? { sourceOrigin: cookie.partitionKey.topLevelSite, hasCrossSiteAncestor: cookie.partitionKey.hasCrossSiteAncestor, } : undefined, }; }); }参见 cdp/BrowserContext.ts#L146-L161。从这段源码可以得到三个实现事实作用域由browserContextId决定默认上下文的#id为undefined即Storage.getCookies不带该参数时查询的就是浏览器默认作用域的全部 Cookie——这正是browser.cookies()能一次拿全的原因。partitionKey.topLevelSite被重命名为sourceOrigin如果你对比过原始 CDP 返回结构与 Puppeteer 结果会发现字段名不一致这是映射层刻意对齐跨浏览器语义的结果BiDi 规范中对应PartitionKey的 source origin。同一接口在 BiDi 后端也有独立实现packages/puppeteer-core/src/bidi/BrowserContext.ts同样实现了cookies()因此该方法在 ChromeCDP与 FirefoxWebDriver BiDi上均可用但由于partitionKey/partitionKeyOpaque等字段标注Supported only in Chrome跨浏览器时以文档字段说明为准。典型使用示例结合源码中deleteMatchingCookies()的依赖方式它先调用cookies()拉全量、再按name/domain/path/url/partitionKey过滤删除见 api/BrowserContext.ts#L315-L364browser.cookies()最常见的用法是读取—断言—清理三步import puppeteer from puppeteer; const browser await puppeteer.launch(); const page await browser.newPage(); await page.goto(https://example.com); // 1. 读取默认上下文的完整 Cookie 列表 const cookies await browser.cookies(); console.log(cookies.map(c ${c.name}${c.value} (expires: ${c.expires}))); // 2. 断言某个分区/属性特征Chrome 特有字段Firefox 可能为 undefined const partitioned cookies.find(c c.partitionKeyOpaque); // 3. 精确清理某个域下的全部 Cookie // 注意deleteMatchingCookies 属于 BrowserContext 方法 await browser.defaultBrowserContext().deleteMatchingCookies({ domain: example.com, }); await browser.close();适用前提与限制browser.cookies()只覆盖默认上下文。若脚本使用了browser.createBrowserContext()创建的隔离上下文Chrome 中即 incognito 上下文各上下文 Cookie/localStorage 相互隔离见 api/BrowserContext.ts#L61-L107 的类注释必须对该上下文实例调用context.cookies()。该方法读取的是浏览器存储层的全量 Cookie与当前页面 URL 无关如果只需要某页面作用域的 Cookie可对比使用页面级的page.cookies()再结合domain/path字段自行过滤。partitionKey、partitionKeyOpaque、priority、sourceScheme等字段文档明确标注 Chrome-only跨浏览器代码中建议做可选字段判断。测试用例中的行为验证仓库的集成测试对该 API 的行为提供了可验证依据test/src/cookies.test.ts 覆盖了 Cookie 设置与读取的核心行为会话 Cookie、过期时间、domain/path 匹配等test/src/browsercontext-cookies.test.ts 验证了不同BrowserContext之间 Cookie 相互隔离、以及上下文级cookies()的读写test/src/defaultbrowsercontext.test.ts 中涉及默认上下文的 Cookie 场景与browser.cookies()走默认上下文路径的语义一致。这些测试文件可以在test/目录配合 Mocha 运行器见 tools/mocha-runner执行用于回归验证 Cookie API 在版本升级后的行为是否稳定。小结Browser.cookies()的定位非常收敛它等价于browser.defaultBrowserContext().cookies()最终在 CDP 后端翻译为一次Storage.getCookies调用返回默认作用域内全部Cookie[]。理解这一点后实践中三个要点即可覆盖绝大多数场景返回对象按Cookie接口解析expires: -1即会话 CookieChrome 独有partitionKeyOpaque只读默认上下文隔离上下文需走BrowserContext.cookies()删除 Cookie 依赖改写expires后写回的机制因此deleteMatchingCookies()这类操作本质上依赖cookies()提供的全量快照作为过滤输入。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考