PageSpy 是一款专为 Web、小程序和 HarmonyOS 应用设计的远程调试工具。它使开发人员能够在各个平台上实时调试应用程序，而无需直接访问目标设备的本机调试工具。本文档提供了 PageSpy 系统的高级概述、架构和主要组件。
什么是 PageSpy?
PageSpy 通过拦截和捕获目标应用程序中的本机 API 调用，将其转换为标准化的消息格式，并将其传输到调试客户端。调试客户端然后通过类似 DevTools 的界面呈现这些信息，允许开发人员检查控制台日志、网络请求、存储、DOM 元素等，类似于他们在浏览器 DevTools 中对待本地应用程序一样。
PageSpy 架起了本地和远程调试之间的桥梁，使在以下方面更容易排除问题：
- 移动设备上的 Web 应用程序
- 小程序（微信、支付宝等）
- 跨平台框架（Taro、UniApp、React Native）
- HarmonyOS 应用程序
- 无法直接访问的远程环境
系统架构
PageSpy 系统由三个主要组件组成：
- SDKs：集成到目标应用程序中的特定平台库
- API 服务器：基于 Go 的后端，用于建立 SDK 和前端之间的通信
- Web 前端：基于 React 的调试界面，模仿浏览器 DevTools
关键组件
SDK 层
SDK 层负责从目标应用程序捕获调试信息并将其发送到 API 服务器。每个 SDK 都是特定于平台的，针对目标环境的独特约束和 API 进行了定制。
| SDK | 目标平台 | 包 |
|---|---|---|
| 浏览器 SDK | Web 应用程序 | @huolala-tech/page-spy-browser |
| 微信 SDK | 微信小程序 | @huolala-tech/page-spy-wechat |
| 支付宝 SDK | 支付宝小程序 | @huolala-tech/page-spy-alipay |
| UniApp SDK | UniApp 框架 | @huolala-tech/page-spy-uniapp |
| Taro SDK | Taro 框架 | @huolala-tech/page-spy-taro |
| Harmony SDK | HarmonyOS 应用程序 | @huolala/page-spy-harmony |
| React Native SDK | React Native 应用程序 | @huolala-tech/page-spy-react-native |
SDK 拦截各种类型的信息：
- 控制台日志 (日志，信息，警告，错误)
- 网络请求（XHR，Fetch）
- JavaScript 错误和未处理的 Promise
- 存储信息 (localStorage, sessionStorage, cookies, indexedDB)
- DOM/Element 交互（用于 Web 平台）
后端 API 服务器
后端 API 服务器采用 Go 编写，作为 SDK 和前端界面之间的通信中心。它处理：
- 房间管理（创建/销毁调试连接）
- 通过 WebSockets 进行实时数据传输
- 会话录制和存储
- 日志持久化
- 身份验证和安全
API 服务器可作为 npm 包（@huolala-tech/page-spy-api）提供，并可使用 Node.js 或 Docker 进行部署。
Web 前端
Web 前端是一个 React 应用程序，提供了一个类似 DevTools 的界面用于调试。它由几个关键组件组成：
DevTools 接口
DevTools 界面是主要的调试界面，模仿浏览器开发者工具。它提供以下面板：
- 控制台面板：查看日志并在目标应用程序中执行 JavaScript
- 网络面板：监视网络请求和响应
- 存储面板：检查 localStorage、sessionStorage、cookies 和 indexedDB
- 系统面板：查看系统信息
- 页面面板：检查页面结构和属性
- 元素面板：检查和操作 DOM 元素（仅适用于 Web 平台）
这些面板旨在是互动的，并从目标应用程序提供实时反馈。
数据流
以下图示了 PageSpy 系统内的数据流程：
插件系统
PageSpy 支持可扩展的插件系统，提供额外功能。三个官方插件可用：
- 数据港插件（@huolala-tech/page-spy-plugin-data-harbor）：支持离线记录和数据导出
- RRWeb 插件（@huolala-tech/page-spy-plugin-rrweb）：提供会话录制和回放功能
- O-Spy 插件（@huolala-tech/page-spy-plugin-ospy）：提供简化集成以快速调试设置
插件会动态加载，并可以根据特定要求进行配置。
部署选项
PageSpy 可以以多种方式部署，以适应不同的环境：
Node.js 部署
npm install -g @huolala-tech/page-spy-api@latest && page-spy-api
Docker 部署
docker run -d --restart=always -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --name="pageSpy" ghcr.io/huolalatech/page-spy-web:latest
部署后，PageSpy 界面可在 http://<server-address>:6752访问。
国际化
PageSpy 支持包括英语、中文、韩语和日语在内的多种语言。国际化系统是使用 i18next 库构建的，可以实现用户界面的无缝翻译。
