PageSpy使用教程

像使用谷歌浏览器的控制台一样简单地开始远程调试。

官方网站

什么是 PageSpy?

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

为什么是 PageSpy?

一图胜千言。

为什么选择 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>",
  },
})

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注