PuppeteerSharp 中 CDPSession 处理 StackTrace 的 JSON 解析问题分析

问题背景

在使用 PuppeteerSharp 14.1.0 版本与 .NET 8 配合时，开发者发现当页面执行 console.info('text') 这类控制台日志操作后，会导致 Page 客户端意外关闭。错误信息表明在解析 Runtime.consoleAPICalled 事件时，JSON 反序列化过程中遇到了 StackTrace 的 parentId 字段解析问题。

错误现象

当页面导航完成后，检查 page.Client.IsClosed 属性会返回 true，关闭原因为 JSON 解析错误："Error reading string. Unexpected token: StartObject. Path 'stackTrace.parentId'"。

根本原因分析

通过调试发现，问题的根源在于 Chrome DevTools Protocol 返回的 consoleAPICalled 事件中，StackTrace 的 parentId 字段实际上是一个包含 id 属性的对象，而非直接字符串值。具体 JSON 结构如下：

"stackTrace": {
  "callFrames": [...],
  "parentId": {
    "id": "19"
  }
}

然而 PuppeteerSharp 中的 StackTrace 类定义将 ParentId 定义为简单的字符串类型：

public string ParentId { get; set; }

这种类型不匹配导致了 Newtonsoft.Json 在反序列化时抛出异常。

技术细节

根据 Chrome DevTools Protocol 官方文档，StackTrace 结构确实应该包含一个 parentId 对象而非简单字符串。这个对象包含一个 id 属性，用于标识父级堆栈跟踪。

在 PuppeteerSharp 的消息处理流程中，CDPSession.OnMessage 方法接收到这种结构时，由于类型定义不匹配，无法正确反序列化，最终导致客户端连接关闭。

解决方案

修复方案需要调整 StackTrace 类的定义，使其与 Chrome DevTools Protocol 规范保持一致。具体有两种实现方式：

1. 将 ParentId 改为包含 id 属性的对象结构
2. 使用 JToken 类型来灵活处理不同类型的输入

在实际修复中，采用了更符合协议规范的方案，即定义专门的 ParentId 对象结构。

影响范围

此问题主要影响以下场景：

• 使用较新版本 Chrome/Chromium 浏览器
• 应用中存在 console.log/info/warn/error 等控制台输出
• 这些控制台调用产生了包含 parentId 的堆栈跟踪信息

开发者建议

对于遇到类似问题的开发者，建议：

1. 升级到包含此修复的 PuppeteerSharp 版本
2. 在自定义消息处理时，注意检查 Chrome DevTools Protocol 的官方规范
3. 对于复杂 JSON 结构，考虑使用 JToken 作为中间类型进行灵活处理

总结

这个问题展示了 API 协议版本兼容性的重要性。随着浏览器内核和 DevTools Protocol 的更新，客户端库需要及时跟进调整数据结构定义。PuppeteerSharp 团队快速响应并修复了这个问题，确保了库的稳定性和兼容性。