持久会话与配置文件

了解 Oxylabs 无头浏览器上的持久（sticky）会话和持久配置文件。可重新连接到进行中的会话，并在多个会话之间复用你的 Cookie 或本地存储。

管理长期运行的多阶段自动化工作流，或在不同连接序列之间维护已登录用户状态，需要持久化浏览器状态。Oxylabs 无头浏览器 提供两种高级持久化系统：

持久会话	在客户端断开连接期间保持远程浏览器环境持续运行。
持久配置文件	保存并恢复 Cookie、local storage 和浏览器缓存。 （需要激活）

持久会话

持久（粘性）会话通过定义自定义 session_name 添加到你的连接 URL：

wss://USER:[e-mail]?session_name=checkout-flow-test

参数	描述	类型
session_name	定义后，会话会一直保留到最大生存时间（TTL）（最长 24 小时或直到停止）。使用相同的 session_name 以重新附加相同的会话 ID 和现有标签页。支持的格式： ^[A-Za-z0-9-]{3,36}$	字符串
keep_alive	当 true （默认），断开连接后会话仍保留在云端（最长至最大 TTL – 24 小时）。 当 false，调用 browser.close() 会回收并关闭会话。	布尔值

重新连接到现有标签页

// 重新连接到现有会话，使用 
const browser = await chromium.connectOverCDP(endpoint);
const ctx = browser.contexts()[0];
const page = ctx.pages().find(p => p.url().includes("http://example.com "));

持久配置文件

持久配置文件 功能和 o_profile 参数默认受限。要访问它们，请联系 Oxylabs 支持（在线客服 或 电子邮件）或你的专属客户经理。

将 Cookie 和 localStorage 保存到命名配置文件中，并在全新的会话中恢复。使用以下参数可让你在多个会话之间保持登录状态，而无需每次重新认证：

参数	描述	类型
o_profile	使用命名配置文件保存/恢复 Cookie 和 localStorage（距上次使用 14 天）。支持的格式： ^[A-Za-z0-9_-]{1,36}$	字符串
o_profile_save	在会话中强制保存配置文件。默认值： true.	布尔值
proxy_resi_ses_id	跨会话固定住宅出口 IP 的自定义会话 ID。支持的格式： ^[A-Za-z0-9]{3,36}$.	字符串
proxy_resi_ses_time	将固定的住宅代理出口 IP 保持的时长，单位为分钟。最小 1，最大 1440 （24 小时）。	整数

每个账号的配置文件数量有上限（max_profiles）。超过限制将返回 CDP_LIMIT_REACHED: profile limit reached 错误。尽可能重用一个稳定的配置文件名称，或联系 Oxylabs 支持（在线客服 或 电子邮件）或你的专属客户经理以提高上限。

可靠的跨会话恢复

对于具有严格机器人监测系统的网站，仅保存 Cookie 并不够。如果恢复的配置文件从不同的住宅出口 IP 连接，你的 Cookie 可能会失效，导致空白页面或安全验证界面。

为确保登录保持一致，请将你的配置文件与固定的住宅出口 IP 配对：

// 会话 1：完成认证并备份状态
const connectionOne = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// 会话 2：使用完全相同的 IP 会话上下文恢复配置文件
const connectionTwo = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";