> 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/chi-jiu-hui-hua-yu-pei-zhi-wen-jian.md).

# 持久会话与配置文件

管理长期运行的多阶段自动化工作流，或在不同连接序列之间维护已登录用户状态，需要持久化浏览器状态。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、local storage 和浏览器缓存。 <em>（需要激活）</em></td></tr></tbody></table>

## 持久会话

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

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

<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>true</code> （默认），断开连接后会话仍保留在云端（最长至最大 TTL – 24 小时）。<br>当 <code>false</code>，调用 <code>browser.close()</code> 会回收并关闭会话。</td><td>布尔值</td></tr></tbody></table>

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

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

## 持久配置文件

{% hint style="warning" %}
**持久配置文件** 功能和 `o_profile` 参数默认受限。要访问它们，请联系 Oxylabs 支持（[在线客服](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理。
{% endhint %}

将 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>true</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`）。超过限制将返回 `CDP_LIMIT_REACHED: profile limit reached` 错误。尽可能重用一个稳定的配置文件名称，或联系 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
// 会话 1：完成认证并备份状态
const connectionOne = "wss://USER:PASS@ubc.oxylabs.io?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// 会话 2：使用完全相同的 IP 会话上下文恢复配置文件
const connectionTwo = "wss://USER:PASS@ubc.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/chi-jiu-hui-hua-yu-pei-zhi-wen-jian.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.