> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/headless-browser/persistent-sessions-and-profiles.md).

# 持久会话与配置文件

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

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

<table data-header-hidden><thead><tr><th width="178"></th><th></th></tr></thead><tbody><tr><td><a href="#persistent-sessions-sticky-sessions"><strong>持久会话</strong></a></td><td>在客户端断开连接期间，保持远程浏览器环境持续运行。</td></tr><tr><td><a href="#persistent-profiles"><strong>持久配置文件</strong></a></td><td>保存并恢复 Cookie、本地存储和浏览器缓存。</td></tr></tbody></table>

## 持久会话

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

```bash
wss://USER:PASS@hb.oxylabs.io?session_name=checkout-flow-test
```

{% hint style="info" %}
持久会话 **默认对所有用户启用** ，默认上限为 **5 个并发会话**. 如果你需要更高上限，请联系 Oxylabs 支持（[在线聊天](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理。
{% endhint %}

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

### 重新连接到现有标签页

```javascript
// 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 保存到命名配置文件中，并在全新的会话中恢复它们。以下参数可让你在不同会话中保持已登录身份，而无需每次重新认证：

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

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

### 可靠的跨会话恢复 <a href="#reliable-cross-session-restore" id="reliable-cross-session-restore"></a>

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

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

```javascript
// Session 1: Authenticate and back up state
const connectionOne = "wss://USER:PASS@hb.oxylabs.io?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:PASS@hb.oxylabs.io?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/cn/headless-browser/persistent-sessions-and-profiles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.