什么是 PageSpy?
PageSpy 是一款兼容 Web / 小程序 / React Native / 鸿蒙 App 等平台项目的开源调试平台。基于对原生 API 的封装,它将调用原生方法时的参数进行过滤、转化,整理成一定格式的消息供调试端消费;调试端收到消息数据后,提供类似本地控制台的功能界面将数据呈现出来。
为什么是 PageSpy?
一图胜千言。

何时使用?
任何无法在本地使用控制台调试的场景,都是 PageSpy 可以大显身手的时候! 一起来看下面的几个场景案例:
- 本地调试 H5、Webview 应用:以往有些产品提供了可以在 H5 上查看信息的面板,但移动端屏幕太小操作不便、显示不友好,以及信息被截断等问题;
- 远程办公、跨地区协同:传统沟通方式如邮件、电话、视频会议等,沟通效率不高、故障信息不全面,容易误解误判;
- 用户终端上出现白屏问题:传统定位问题的方式包括数据监控、日志分析等,这些方式依赖排障人员要理解业务需求场景、技术实现;
PageSpy 的目标,就是为包括以上场景的人员提供帮助。
服务部署
使用 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
执行完成后,打开浏览器访问 http://localhost:6752 即可访问服务。
视频学习
客户端部署
浏览器
导入 SDK
<!-- PageSpy SDK -->
<script crossorigin="anonymous" src="https://<your-pagespy-host>/page-spy/index.min.js"></script>
<!-- 插件(非必须,但建议使用) -->
<script crossorigin="anonymous" src="https://<your-pagespy-host>/plugin/data-harbor/index.min.js"></script>
<script crossorigin="anonymous" src="https://<your-pagespy-host>/plugin/rrweb/index.min.js"></script>
初始化 PageSpy 和插件
window.$harbor = new DataHarborPlugin();
window.$rrweb = new RRWebPlugin();
[window.$harbor, window.$rrweb].forEach((p) => {
PageSpy.registerPlugin(p);
});
window.$pageSpy = new PageSpy({
// 配置项
api?: string;
clientOrigin?: string;
// "project" is an aggregation of information that can be searched in the room list on the debug side.
// default: 'default'
project?: string;
// "title" is a user-defined parameter that can be used to distinguish the current debugging client,
// and the corresponding information is displayed under the "device id" in each debugging connection panel.
// default: '--'
title?: string;
// Indicates whether the SDK will automatically render the "Circle with Logo on White Background"
// control in the bottom left corner of the client when initiation is complete. If set to false,
// you can call window.$pageSpy.render() to render it manually.
// default: true
autoRender?: boolean;
// Manually specify the scheme of the PageSpy service.
// This works if the SDK can't correctly analyse the scheme, e.g. if PageSpy's browser plugin
// is introduced into the SDK via chrome-extension://xxx/sdk/index.min.js, which will be
// be parsed by the SDK as an invalid "chrome-extension://" and fallback to ["http://", "ws://"].
// - (Default) Pass the value undefined or null: the SDK will parse it automatically;
// - Pass boolean value:
// - true: the SDK will access the PageSpy service via ["https://", "wss://"].
// - false: the SDK will access the PageSpy service via ["http://", "wss://"]
enableSSL?: boolean | null;
// All internal plugins are carried with PageSpy by default out of the box.
// You can disable some plugins as needed.
disabledPlugins?: (InternalPlugins | string)[];
// After adding support for offline replay in PageSpy@1.7.4, the client-integrated SDK can work without
// establishing a connection with the debugger.
// Default value is false, when users set it to other values will enters "offline mode", where PageSpy
// will not create rooms or establish WebSocket connections.
offline?: boolean;
// Customize logo source url.
logo?: string;
});
小程序
导入 SDK
在项目中安装依赖。我们提供了几种小程序平台的 SDK,请根据需要安装:
- 微信小程序
yarn add @huolala-tech/page-spy-wechat@latest
- 支付宝小程序
yarn add @huolala-tech/page-spy-alipay@latest
- UniAPP
yarn add @huolala-tech/page-spy-uniapp@latest
- Taro
yarn add @huolala-tech/page-spy-taro@latest
配置白名单
将 PageSpy 服务域名填入小程序的 http、websocket 请求白名单中。注意除了开发环境,小程序强制要求使用 https 和 wss 协议:
https://<your-pagespy-host>
wss://<your-pagespy-host>
初始化 PageSpy 和插件
在入口文件中引入 SDK 并实例化,初始化参数提供了可选的 配置项 用于自定义 SDK 的行为:
import PageSpy from "@huolala-tech/page-spy-wechat";
const $pageSpy = new PageSpy({
api: "<your-pagespy-host>",
});
鸿蒙 App
导入 SDK
在待调试 HAP 目录下安装依赖:
# API 9
ohpm install @huolala/page-spy-harmony@^1.0.0
# API 11
ohpm install @huolala/page-spy-harmony@^2
初始化 PageSpy 和插件
在合适的位置引入 SDK 并初始化,这里以 EntryAbility 为例。初始化参数提供了可选的 配置项 用于自定义 SDK 的行为:
import { PageSpy } from "@huolala/page-spy-harmony";
import axiosInstance from "path/to/your/axios-instance";
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
new PageSpy({
context: this.context,
api: "<your-pagespy-host>",
enableSSL: true,
axios: axiosInstance,
});
}
}
常用 API
更新初始化参数
PageSpy 提供了 Device ID 用于识别设备,同时还提供了 project / title 供开发者在初始化时自定义信息,用于辅助识别客户端。但你可能希望在初始化之后更新这些参数信息,操作方式如下:
// 调用 updateRoomInfo 可以更新 project / title
window.$pageSpy.updateRoomInfo({ project: "xxx", title: "xxx" });
显示隐藏按钮
window.$pageSpy = new PageSpy({
// ... 其他配置参数
autoRender: false,
});
手动渲染「圆形白底带 Logo」的控件
当
config.autoRender为false时,需要手动调用render()方法渲染控件。
window.$pageSpy.render();
销毁
PageSpy 会断开连接、从文档中移除相关 DOM、清空已缓存的数据、调用所有已注册插件的 onReset() 方法。
当前上下文中被代理或者被重写的 API,如浏览器中的 window.fetch,都会恢复到实例化 PageSpy 之前的状态。
window.$pageSpy.abort();
常见问题
调试端如何加一些安全认证的保护,开发者通过认证才可以访问?
从 2.3.0 版本开始,PageSpy 支持在启动服务时使用变量设置密码以保护调试端安全。设置密码后,开发者访问调试面板时必须输入正确的密码。
允许输入的变量和含义:
- AUTH_PASSWORD:设置密码;
- JWT_SECRET:设置 token 的密钥;
- JWT_EXPIRATION_HOURS:设置 token 过期时间(小时),默认 24 小时;
在启动服务时设置,具体的使用方式如下:
docker run -d --restart=always -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --name="pageSpy" -e AUTH_PASSWORD=<password> -e JWT_SECRET=<secret> -e JWT_EXPIRATION_HOURS=<hours> ghcr.io/huolalatech/page-spy-web:latest
2.3.0 之前的版本如何设置密码?
“` Nginx 配置
auth_basic “请输入用户名和密码以访问 PageSpy 服务”;
auth_basic_user_file /etc/nginx/.htpasswd;
## 预览页面 CORS
```yml
server
{
# 设置CORS
# 指定响应资源是否允许与给定的 origin 共享
add_header Access-Control-Allow-Origin '*';
add_header Access-Control-Allow-Credentials 'true';
# 配置允许跨域的请求方法
add_header Access-Control-Allow-Methods 'GET,POST,PUT,DELETE,Options';
# 配置允许跨域的请求头
# add_header Access-Control-Allow-Headers 'Authorization,Content-Type,Accept,Origin,User-Agent,Cache-Control,X-Mx-ReqToken,X-Requested-With';
}
更改按钮大小和图片大小
#__pageSpy .page-spy-logo {
width: 50px;
height: 50px;
}
#__pageSpy .page-spy-logo img {
width: 30px;
height: 30px;
}
主题(个性化)设置
new PageSpy({
...,
primaryColor: "<主题色>",
logo: "<悬浮球上的 logo>",
modal: {
title: "<弹窗上的标题>",
logo: "<弹窗上的 logo>",
},
})