持久会话和配置文件

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

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

持久会话	在客户端断开连接期间，保持远程浏览器环境持续运行。
持久配置文件	保存并恢复 Cookie、本地存储和浏览器缓存。

持久会话

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

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

持久会话 默认对所有用户启用 ，默认上限为 5 个并发会话. 如果你需要更高上限，请联系 Oxylabs 支持（在线聊天 或 电子邮件）或你的专属客户经理。

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

重新连接到现有标签页

// Reconnect to existing session with 
const browser = await chromium.connectOverCDP(endpoint);
const ctx = browser.contexts()[0];
const page = ctx.pages().find(p => p.url().includes("http://example.com "));

持久配置文件

持久配置文件 默认对所有用户启用 ，默认上限为 5 个配置文件. 使用它可将 Cookie 和 localStorage 保存到命名配置文件中，并在全新的会话中恢复它们。以下参数可让你在不同会话中保持已登录身份，而无需每次重新认证：

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

超过 max_profiles 限制 5 返回 CDP_LIMIT_REACHED: profile limit reached 错误。你可以在控制面板（hb.oxylabs.io/dashboard）中直接查看并删除已保存的配置文件，若达到上限，也可以重复使用一个稳定的配置文件名称。若需要更高上限，请联系 Oxylabs 支持（在线聊天 或 电子邮件）或你的专属客户经理。

可靠的跨会话恢复

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

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

// Session 1: Authenticate and back up state
const connectionOne = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// Session 2: Restore profile with the exact same IP session context
const connectionTwo = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";