---
name: 会话管理
description: 同时运行多个隔离的浏览器会话、管理持久化配置文件、并排比较不同浏览器状态、并行抓取或A/B测试流程。
---

# 会话管理

> **何时使用**：同时运行多个隔离的浏览器会话、管理持久化配置文件、并排比较不同浏览器状态、并行抓取或 A/B 测试流程。
> **前置条件**：[core-commands.md](core-commands.md) 了解基本 CLI 用法

## 快速参考

```bash
# 命名会话：每个会话拥有独立的 Cookie、存储、标签页
playwright-cli -s=auth open https://app.example.com/login
playwright-cli -s=public open https://example.com

# 在会话内交互
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot

# 列出所有活跃会话
playwright-cli list

# 清理
playwright-cli -s=auth close
playwright-cli close-all             # 关闭所有会话
playwright-cli kill-all              # 强制杀死僵尸进程
```

## 命名会话

使用 `-s=<name>` 标志创建隔离的浏览器实例。每个命名会话拥有独立的：

- Cookie
- localStorage / sessionStorage
- IndexedDB
- 缓存
- 浏览历史
- 打开的标签页

### 创建会话

```bash
# 为身份验证测试创建会话
playwright-cli -s=admin open https://app.example.com/login

# 为不同用户创建独立会话
playwright-cli -s=viewer open https://app.example.com/login

# 会话中的所有命令相互隔离
playwright-cli -s=admin fill e1 "admin@company.com"
playwright-cli -s=admin fill e2 "admin-password"
playwright-cli -s=admin click e3

playwright-cli -s=viewer fill e1 "viewer@company.com"
playwright-cli -s=viewer fill e2 "viewer-password"
playwright-cli -s=viewer click e3
```

### 默认会话

当省略 `-s` 时，所有命令共享同一个默认会话：

```bash
# 以下命令均使用同一个默认会话
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e1
playwright-cli close
```

## 会话隔离

会话完全独立——一个会话中的操作不会影响其他会话：

```bash
# 会话 A 以管理员身份登录
playwright-cli -s=admin open https://app.example.com
playwright-cli -s=admin fill e1 "admin@example.com"
playwright-cli -s=admin fill e2 "admin-pass"
playwright-cli -s=admin click e3

# 会话 B 访问同一网站——未登录状态
playwright-cli -s=guest open https://app.example.com
playwright-cli -s=guest snapshot
# 显示登录页面，而非管理面板

# 会话 C 可使用完全不同的浏览器
playwright-cli -s=firefox-test open https://app.example.com --browser=firefox
```

## 会话命令

```bash
# 列出所有活跃会话及其状态
playwright-cli list

# 关闭指定的命名会话
playwright-cli -s=mysession close

# 关闭默认会话
playwright-cli close

# 同时关闭所有会话
playwright-cli close-all

# 强制杀死所有浏览器守护进程（用于卡死/僵尸浏览器）
playwright-cli kill-all

# 删除会话的持久化配置文件数据
playwright-cli -s=mysession delete-data

# 删除默认会话数据
playwright-cli delete-data
```

## 持久化配置文件

默认情况下，会话在**内存**中运行——关闭会话后所有 Cookie、存储和浏览数据都将丢失。使用 `--persistent` 将状态保存到磁盘。

### 自动生成的配置文件

```bash
# Playwright-cli 自动管理配置文件目录
playwright-cli -s=myapp open https://example.com --persistent

# 关闭后重新打开——Cookie 和存储将被保留
playwright-cli -s=myapp close
playwright-cli -s=myapp open https://example.com --persistent
# 仍然处于登录状态！
```

### 自定义配置文件目录

```bash
# 指定配置文件数据的存储位置
playwright-cli -s=myapp open https://example.com --profile=/tmp/my-browser-profile

# 可用于在会话之间共享配置文件
playwright-cli -s=session-a open https://example.com --profile=/shared/profile
playwright-cli -s=session-a close
playwright-cli -s=session-b open https://example.com --profile=/shared/profile
```

### 清理持久化数据

```bash
# 删除存储的配置文件数据（必须先关闭会话）
playwright-cli -s=myapp close
playwright-cli -s=myapp delete-data
```

## 会话配置

按会话配置浏览器引擎和选项：

```bash
# 不同会话使用不同浏览器
playwright-cli -s=chrome-test open https://example.com --browser=chrome
playwright-cli -s=firefox-test open https://example.com --browser=firefox
playwright-cli -s=webkit-test open https://example.com --browser=webkit
playwright-cli -s=edge-test open https://example.com --browser=msedge

# 使用配置文件
playwright-cli -s=configured open https://example.com --config=my-config.json

# 有头模式（显示浏览器窗口）
playwright-cli -s=visible open https://example.com --headed

# 通过扩展连接现有浏览器
playwright-cli -s=extension open --extension
```

## 环境变量

设置默认会话名称，使所有命令无需 `-s` 标志即可使用：

```bash
export PLAYWRIGHT_CLI_SESSION="mysession"

# 以下命令将自动使用 "mysession"
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close
```

## 常见模式

### 多用户角色测试

同时以不同用户角色测试同一应用：

```bash
# 管理员会话
playwright-cli -s=admin open https://app.example.com/login
playwright-cli -s=admin snapshot
playwright-cli -s=admin fill e1 "admin@company.com"
playwright-cli -s=admin fill e2 "admin-pass"
playwright-cli -s=admin click e3

# 普通用户会话
playwright-cli -s=user open https://app.example.com/login
playwright-cli -s=user fill e1 "user@company.com"
playwright-cli -s=user fill e2 "user-pass"
playwright-cli -s=user click e3

# 比较每个角色看到的内容
playwright-cli -s=admin snapshot     # 应显示管理面板
playwright-cli -s=user snapshot      # 不应显示管理面板

playwright-cli -s=admin screenshot --filename=admin-view.png
playwright-cli -s=user screenshot --filename=user-view.png
```

### 并发抓取

并行抓取多个网站以提高速度：

```bash
#!/bin/bash

# 同时启动所有浏览器
playwright-cli -s=site1 open https://site1.example.com &
playwright-cli -s=site2 open https://site2.example.com &
playwright-cli -s=site3 open https://site3.example.com &
wait

# 从每个会话收集数据
playwright-cli -s=site1 snapshot --filename=site1.yaml
playwright-cli -s=site2 snapshot --filename=site2.yaml
playwright-cli -s=site3 snapshot --filename=site3.yaml

# 截取屏幕截图
playwright-cli -s=site1 screenshot --filename=site1.png
playwright-cli -s=site2 screenshot --filename=site2.png
playwright-cli -s=site3 screenshot --filename=site3.png

# 清理
playwright-cli close-all
```

### A/B 测试比较

```bash
# 变体 A
playwright-cli -s=variant-a open "https://app.example.com?variant=a"
playwright-cli -s=variant-a screenshot --filename=variant-a.png

# 变体 B
playwright-cli -s=variant-b open "https://app.example.com?variant=b"
playwright-cli -s=variant-b screenshot --filename=variant-b.png

# 并排比较
playwright-cli close-all
```

### 跨浏览器测试

在多个浏览器中运行同一流程以验证兼容性：

```bash
#!/bin/bash

for browser in chrome firefox webkit; do
  playwright-cli -s=$browser open https://example.com --browser=$browser
  playwright-cli -s=$browser snapshot
  playwright-cli -s=$browser screenshot --filename="$browser-home.png"

  playwright-cli -s=$browser goto https://example.com/features
  playwright-cli -s=$browser screenshot --filename="$browser-features.png"
done

playwright-cli close-all
```

### 跨会话共享认证状态

```bash
# 登录一次并保存状态
playwright-cli -s=login open https://app.example.com/login
playwright-cli -s=login fill e1 "user@example.com"
playwright-cli -s=login fill e2 "password123"
playwright-cli -s=login click e3
playwright-cli -s=login state-save auth.json
playwright-cli -s=login close

# 在多个会话中复用认证状态
playwright-cli -s=session-a open https://app.example.com
playwright-cli -s=session-a state-load auth.json
playwright-cli -s=session-a goto https://app.example.com/dashboard

playwright-cli -s=session-b open https://app.example.com
playwright-cli -s=session-b state-load auth.json
playwright-cli -s=session-b goto https://app.example.com/settings
```

## 最佳实践

### 1. 使用语义化命名会话

```bash
# 良好：用途清晰
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com
playwright-cli -s=checkout-flow open https://shop.example.com

# 避免：泛化命名
playwright-cli -s=s1 open https://github.com
playwright-cli -s=test open https://docs.example.com
```

### 2. 始终进行清理

```bash
# 完成后关闭单个会话
playwright-cli -s=auth close
playwright-cli -s=scrape close

# 或一次性关闭所有会话
playwright-cli close-all

# 如果浏览器无响应
playwright-cli kill-all
```

### 3. 删除过期的持久化数据

```bash
# 删除旧的持久化配置文件以释放磁盘空间
playwright-cli -s=old-session delete-data
```

### 4. 单任务工作使用默认会话

当只需要一个浏览器时，无需创建命名会话：

```bash
# 简单的单会话工作流——不需要 -s 标志
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e1
playwright-cli close
```

### 5. 结合状态管理

对于长时间运行的任务，定期保存状态：

```bash
playwright-cli -s=long-task open https://app.example.com --persistent
# ……多次交互……
playwright-cli -s=long-task state-save checkpoint.json
# ……更多交互……
# 如果出现问题，恢复状态：
playwright-cli -s=long-task state-load checkpoint.json