Puppeteer CookiePriority 类型详解Cookie 的 Low/Medium/High 优先级及其在页面级与浏览器级 Cookie API 中的应用【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer本篇技术指南以 Puppeteer 的 API 文档 CookiePriority 类型定义 为核心深入讲解 Cookie 的 Priority优先级概念、类型取值语义以及该类型在page.setCookie等页面级 Cookie API 与浏览器级 Cookie API 中的真实使用方式并结合仓库源码还原其经由 CDPNetwork.setCookies与 WebDriver BiDi 协议下发到底层浏览器实现的完整调用链。读完本文你将能准确理解并在自动化脚本中正确使用带优先级的 Cookie。什么是 Cookie 的 Priority 与 CookiePriority 类型Cookie 的Priority优先级表示服务端设置的 Cookie 在浏览器中的优先状态其规范来源是 IETF 草案draft-west-cookie-priority-00。该机制设计的核心动机是当网站在同一域名下设置的 Cookie 数量接近或超出浏览器配额上限时浏览器需要决定淘汰哪些 Cookie、保留哪些 Cookie拥有更高优先级的 Cookie 应被优先保留而低优先级的 Cookie 更容易在配额压力下被清理。Puppeteer 在 packages/puppeteer-core/src/common/Cookie.ts 中把这一概念建模为一个字符串联合类型/** * Represents the cookies Priority status: * https://tools.ietf.org/html/draft-west-cookie-priority-00 * * public */ export type CookiePriority Low | Medium | High;该类型被声明为public是 Puppeteer 公共 API 的组成部分因此在 docs/api/index.md 的类型索引、CookieParam 文档 与 CookieData 文档 中都有引用。取值语义CookiePriority只有三个合法取值且大小写必须严格匹配取值语义相对地位Low低优先级 Cookie配额紧张时最容易被淘汰Medium中优先级 Cookie默认档位介于两者之间High高优先级 Cookie配额紧张时优先被保留可以推断三个取值之间存在Low Medium High的相对次序关系浏览器在 Cookie 总量超过单域名host配额时会依据这一次序优先淘汰低优先级条目、保护高优先级条目。如果某个 Cookie 在设置时未显式携带 Priority 属性则按草案与 Chromium 的一贯处理逻辑它会被当作Medium中优先级对待——也就是说大多数普通 Cookie 天然处于中档只有需要特殊保护的会话或关键 Cookie 才建议显式提升为High。CookiePriority 在 Puppeteer 类型体系中的位置CookiePriority不是孤立存在的类型它和几个 Cookie 相关的类型共同定义在 packages/puppeteer-core/src/common/Cookie.ts 这一个模块中CookieSameSite Strict | Lax | None | DefaultCookie 的 SameSite 状态CookiePriority Low | Medium | HighCookie 的 Priority 状态CookieSourceScheme Unset | NonSecure | Secure设置 Cookie 的原始源 schemeCookiePartitionKeyChrome 中 Cookie 分区键Cookie读取查询返回的 Cookie 对象模型CookieParam页面级Cookie 写入参数的输入模型CookieData浏览器级Cookie 写入参数的输入模型DeleteCookiesRequest删除 Cookie 的请求模型。也就是说CookiePriority主要负责写入set方向——它作为一个可选的输入字段出现在两个参数对象中而读取方向的Cookie模型则通过继承CookieData间接触及该字段。从类型层面看该字段在两种参数中声明方式完全一致均标记为仅在 Chrome 中支持。核心使用位置一页面级 API 的 CookieParamCookieParam是 Puppeteer 页面级 Cookie APIPage.setCookie()使用的参数对象。在 common/Cookie.ts 中它包含以下字段export interface CookieParam { name: string; // Cookie 名称必填 value: string; // Cookie 值必填 url?: string; // 与 Cookie 关联的 request-URI会影响默认 domain、path 与 source scheme domain?: string; // Cookie 所属域名 path?: string; // Cookie 路径 secure?: boolean; // 是否仅通过 HTTPS 传输 httpOnly?: boolean; // 是否禁止脚本读取HttpOnly sameSite?: CookieSameSite; // SameSite 属性 expires?: number; // 过期时间UNIX 秒不设置则为会话 Cookie priority?: CookiePriority; // Cookie 优先级仅 Chrome 支持 sourceScheme?: CookieSourceScheme; // source scheme仅 Chrome 支持 partitionKey?: CookiePartitionKey | string; // 分区键 }其中priority字段的文档注释为Cookie Priority. Supported only in Chrome.这明确了两点其一它是可选字段不传时采用浏览器默认行为其二它只在基于 Chromium 的浏览器Chrome / Edge 等中生效。使用页面级 API 时典型场景是构造用户已登录态的 Cookie 集合并写入页面await page.setCookie({ name: session_token, value: a1b2c3d4e5, domain: example.com, path: /, httpOnly: true, secure: true, priority: High, // 高优先级帮助其在 Cookie 配额紧张时被保留 });核心使用位置二浏览器级 API 的 CookieDataCookieData是浏览器级 Cookie API 使用的参数对象相关方法包括Browser.setCookie()、BrowserContext.setCookie()等注意Browser层会委托给其默认BrowserContext见 api/Browser.ts。在 common/Cookie.ts 中它包含export interface CookieData { name: string; // Cookie 名称必填 value: string; // Cookie 值必填 domain: string; // Cookie 所属域名必填 path?: string; secure?: boolean; httpOnly?: boolean; sameSite?: CookieSameSite; expires?: number; priority?: CookiePriority; // Cookie 优先级仅 Chrome 支持 sourceScheme?: CookieSourceScheme; partitionKey?: CookiePartitionKey | string; }与CookieParam相比CookieData的显著差异是domain成为必填字段浏览器级写入不针对某个已加载页面因此必须显式给出域名且不提供url字段。浏览器级写入的典型示例import puppeteer from puppeteer; const browser await puppeteer.launch(); const context browser.defaultBrowserContext(); await context.setCookie({ name: preferred_locale, value: zh-CN, domain: example.com, path: /, expires: Math.floor(Date.now() / 1000) 86400, priority: Medium, });// 或者等价地直接使用 Browser 级别 API内部委托给默认 BrowserContext await browser.setCookie({ name: preferred_locale, value: zh-CN, domain: example.com, priority: Low, });为什么 CookiePriority 仅在 Chrome 中支持该字段的Chrome only限定既来自 Chromium 对该草案的采纳也反映在 Puppeteer 的协议实现差异中CDPChrome DevTools Protocol路线CDP 的Network.setCookies命令原生支持Network.CookieParam.priority字段枚举Low/Medium/High因此 Puppeteer 走 CDP 时可以把priority原样下发。WebDriver BiDi 路线Firefox 通过 BiDi 协议驱动标准的 BiDistorage.setCookie参数并不包含优先级字段。因此在 BiDi 实现中priority被 Puppeteer 归类为Chrome-specific propertyChrome 专属属性单独传递只有在底层浏览器为 Chromium 时才真正有意义。这也印证了文档中Supported only in Chrome的注释——当自动化目标为 Firefox 时该字段不应作为功能依赖。这一设计也从侧面说明Cookie 的 Priority 属于 Chromium 生态对 Cookie 规范的扩展能力并非 Web 标准中所有浏览器均实现的行为。源码级解析priority 到底是如何传到浏览器的CDP 路线字段直通 Network.setCookies在 cdp/Page.ts 中Page.setCookie()的实现思路是先把每个参数做基础校验与补全例如当页面 URL 以http开头且未显式提供url时自动用当前页面 URL 填充拒绝在about:blank、data:页面设置 Cookie随后先调用deleteCookie清理同名 Cookie最后通过主目标会话发送 CDP 命令await this.#primaryTargetClient.send(Network.setCookies, { cookies: items.map(cookieParam { return { ...cookieParam, partitionKey: convertCookiesPartitionKeyFromPuppeteerToCdp( cookieParam.partitionKey, ), sameSite: convertSameSiteFromPuppeteerToCdp(cookieParam.sameSite), }; }), });注意这里的...cookieParam展开由于CookieParam中的priority字段名与 CDPNetwork.CookieParam.priority完全同名它会被直接透传给底层 Chromium不需要任何额外映射。这也是 Puppeteer 在 CDP 路线下处理该字段最核心的实现事实——Puppeteer 层的类型约束保证了调用方只能传入Low | Medium | High之一从而与 CDP 协议的枚举约束保持一致。WebDriver BiDi 路线作为 Chrome 专属属性转发在 BiDi 路线下页面级与浏览器级的setCookie实现分别位于 bidi/Page.ts 与 bidi/BrowserContext.ts。以浏览器级为例Puppeteer 先构造 BiDi 的PartialCookiedomain、name、value、path、httpOnly、secure、sameSite、expiry 等字段随后把 source scheme、优先级、url 这类 Chrome 专属属性一并收集...cdpSpecificCookiePropertiesFromPuppeteerToBidi( cookie, sourceScheme, priority, url, ),从源码结构看cdpSpecificCookiePropertiesFromPuppeteerToBidi这类辅助函数专门负责在 Puppeteer 与 BiDi 之间搬运 Chromium 特有的 Cookie 字段而priority名列其中再次印证该能力被 Puppeteer 团队定性为 Chromium 专有能力而非通用 Web 能力。实际使用中的注意事项取值必须严格匹配大小写类型上只允许Low、Medium、High三个字符串字面量。使用 TypeScript 时编译器会拦截拼写错误使用纯 JavaScript 时则需自行保证拼写正确否则运行时可能被浏览器忽略或报错。它不是会话保活的银弹Priority 只在 Cookie 数量逼近配额、需要驱逐部分条目时起作用它不会阻止网站服务端主动过期或删除 Cookie。务必配合 domain/path 使用特别是浏览器级 APICookieDatadomain是必填项页面级 API 则可借助url字段或已加载页面自动推导。字段配合错误会导致 Cookie 写入的位置与预期不符。读取方向不要强依赖 priority 回读Puppeteer 查询 Cookie 返回的是Cookie模型继承CookieData。对 Chrome 而言通过 CDP 读取的 Cookie 通常不包含 priority 字段因此不要把读回 priority 断言设置是否成功作为验证手段更可靠的验证方式是读取 Cookie 的 name/value/domain/path 等稳定字段。对 Firefox 无效由于优先级是 Chrome 专属能力使用puppeteer驱动 FirefoxBiDi时不要依赖该字段实现关键逻辑。Puppeteer 支持 Firefox 的浏览器清单与能力差异可参考 supported-browsers.md。一个完整的可运行示例综合以上内容下面是一个既覆盖页面级设置、又覆盖浏览器级设置的完整脚本演示CookiePriority三种取值的落点import puppeteer from puppeteer; const browser await puppeteer.launch({headless: true}); // 1) 浏览器级在默认 BrowserContext 中预置带优先级的 Cookie await browser.setCookie( { name: banner_dismissed, value: 1, domain: example.com, path: /, priority: Low, // 广告/横幅类低价值 Cookie配额紧张时先被淘汰 }, { name: auth_uid, value: user-42, domain: example.com, path: /, httpOnly: true, secure: true, priority: High, // 关键认证 Cookie尽力保留 }, ); const page await browser.newPage(); await page.goto(https://example.com, {waitUntil: networkidle2}); // 2) 页面级在页面会话期间补充一个中优先级 Cookie await page.setCookie({ name: ui_theme, value: dark, url: https://example.com, priority: Medium, }); // 3) 读取验证Chrome 下一般读不回 priority验证稳定的基础字段 const cookies await page.cookies(); const auth cookies.find(c c.name auth_uid); console.log(auth?.name, auth?.value, auth?.domain, auth?.path); await browser.close();小结与延伸阅读CookiePriority是 Puppeteer Cookie API 中一个轻量但定位明确的类型它以Low | Medium | High三个字符串字面量刻画 Cookie 的淘汰优先级主要服务于在 Cookie 总量超配时优先保留关键会话这一自动化场景在实现上CDP 路线通过同名字段直通Network.setCookiesBiDi 路线则将其作为 Chrome 专属属性转发二者共同决定了仅在 Chrome 中支持这一公共契约。如果你想进一步了解它与其它 Cookie 字段的配合方式推荐阅读仓库中的以下材料CookiePriority 类型文档本文主题的原始 API 参考页CookieParam 参数对象文档页面级写入参数全字段说明CookieData 参数对象文档浏览器级写入参数全字段说明Page.setCookie 文档 与 BrowserContext.setCookie 文档两组 API 的语义与示例common/Cookie.tsCookiePriority、CookieParam、CookieData的类型源头cdp/Page.tspriority经Network.setCookies透传的实现bidi/BrowserContext.tsBiDi 路线下priority作为 Chrome 专属属性转发的实现。【免费下载链接】puppeteerJavaScript API for Chrome and Firefox项目地址: https://gitcode.com/GitHub_Trending/puppeteer1/puppeteer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考