Playwright-Python中storage_state加载Cookie的正确使用方式

在自动化测试和爬虫开发中，Cookie管理是一个常见需求。Playwright-Python作为流行的浏览器自动化工具，提供了多种Cookie操作方式，其中通过storage_state参数加载Cookie是官方推荐的方法之一。然而，许多开发者在使用过程中会遇到Cookie无法正确加载的问题，这通常是由于数据结构不符合预期导致的。

问题现象

开发者尝试通过以下方式加载Cookie文件：

context = browser.new_context(storage_state="cookies.json")

当cookies.json文件内容为数组格式时：

[
  {
    "name": "ABC",
    "value": "1111",
    "domain": ".test.com",
    "path": "/",
    "expires": 1755849293.606346,
    "httpOnly": false,
    "secure": false,
    "sameSite": "Lax"
  }
]

实际运行时发现Cookie并未被正确加载，context.cookies()返回空列表。而如果改用add_cookies()方法手动添加同样的Cookie数据却能正常工作。

根本原因

问题的根源在于storage_state参数期望的JSON数据结构与开发者提供的不匹配。Playwright-Python要求storage_state文件必须包含特定的顶层结构，而不仅仅是Cookie数组。

正确解决方案

正确的JSON文件结构应该包含"cookies"键，其值为Cookie数组：

{
    "cookies": [
        {
            "name": "ABC",
            "value": "1111",
            "domain": ".test.com",
            "path": "/",
            "expires": 1755849293.606346,
            "httpOnly": false,
            "secure": false,
            "sameSite": "Lax"
        }
    ]
}

这种结构是Playwright-Python官方文档明确要求的格式。它不仅能存储Cookie，还可以存储localStorage和sessionStorage等其他存储状态。

最佳实践建议

1. 数据结构验证：在使用storage_state前，确保JSON文件符合Playwright要求的格式规范
2. 生成方式：建议通过context.storage_state()方法自动生成存储状态文件，而非手动创建
3. 调试技巧：当Cookie加载失败时，可以先检查context.cookies()返回值，再对比文件内容
4. 兼容性考虑：注意不同Playwright版本可能对数据结构有细微要求差异

替代方案比较

虽然add_cookies()方法可以临时解决问题，但与storage_state相比存在以下不足：

• 无法保存和恢复完整的浏览器状态（如localStorage）
• 需要额外的代码逻辑管理Cookie持久化
• 在多页面场景下管理不够方便

因此，对于需要持久化浏览器状态的场景，正确使用storage_state仍然是首选方案。

通过理解Playwright-Python对存储状态的格式要求，开发者可以避免常见的Cookie加载问题，构建更健壮的浏览器自动化脚本。