一文带你了解 PageSpy，开启前端调试新姿势

[blucas01]

前言

推荐一款多端的开源调试工具 PageSpy ，官方地址：https://pagespy.org 。

这款工具可以拿来做什么？如何使用？

接下来的内容会一一说明，你也可以前往官网的回放实验室体验：https://pagespy.org/#/replay-lab 。

介绍

日常开发中，项目出现问题基本都会通过 本地浏览器控制台 排查。可有些时候因为无法使用控制台，而导致排查故障需要多花费很多时间和人力，比如：

• 真机调试 H5：以往有产品提供了可以在 H5 上查看信息的面板，但真机屏幕太小操作不便、显示不友好，以及数据会被截断；

• 远程办公、异地协同：传统沟通方式如邮件、电话、视频等，沟通问题的周期长、效率不高、故障信息不全面，容易误解误判；

• 用户设备白屏：除了需要提前获知出现问题的用户信息，定位问题的方式包括查看数据监控、日志分析，甚至还要跑到客户现场等，这些方式依赖排障人员要理解业务场景、技术实现；

• 全局的 "问题反馈" 组件

  点击查看示例图：问题反馈表单组件。

  大多注重用户体验的网站，会在产品端为用户提供反馈问题的表单组件。从用户的角度这确实会提升好感，但用户提交的内容对于排查问题的帮助可能并不大，根本原因是：用户提交的基本上是文字概述和截图，或许还包含用户信息，但开发者更希望看到的是：

  • 用户是如何操作的；
  • 伴随着操作，程序的运行时行为数据。例如：打印的日志、发出的网络请求以及响应数据等；

上述场景中列举的问题的共同点是：开发者无法像使用本地控制台一样查看程序运行信息。

你也被这些问题困扰了吗？那 PageSpy 可以给你一些帮助。

能力

为了方便理解，我们通过实例对 PageSpy 的使用场景和能力进行说明。

PageSpy 在线实时调试

产品联调期间，测试人员上报问题后，开发者通过 「 PageSpy 在线实时调试」 查看程序的运行数据，其中包括实时的 Console 、Network 、Page 、Storage 以及 System 信息，还可以发送代码到真机上执行；

PageSpy 日志回放调试

假设你开发的工厂系统已经上线、交付使用，某日系统使用人员反馈某个流程不符合预期，但是由于办公地点不同你们只能线上交流。

系统接入 PageSpy 之前，定位问题可能需要对方提供：

• 问题的现象说明；
• 在不同流程状态下的截图；
• 控制台面板的信息（这是有很高门槛的）： 如 Console 面板的日志、Network 面板的数据；
• 等等……

系统接入 PageSpy 之后，收到类似的反馈只需告诉对方 上传日志 即可。（不用担心！上传 / 下载离线日志的功能 PageSpy 都已经提供。）

对方上传完成后就可以前往回放调试，开发者除了可以看到运行时数据外，还可以看到用户的操作轨迹。

深入

PageSpy 组成

PageSpy 主要由三个模块部分组成：

• 在项目中引入的 SDK ，源代码在 HuolalaTech/page-spy 维护；
• 开发者查看数据的调试端，源代码在 HuolalaTech/page-spy-web 维护；
• 在 SDK 和调试端之间转发消息的服务端，源代码在 HuolalaTech/page-spy-api 仓库维护；

使用

首先是考虑用户隐私和数据安全、其次为了方便大家使用，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
  

• 使用 Node 部署

  yarn global add @huolala-tech/page-spy-api@latest && page-spy-api
  
  # 或者
  
  npm install -g @huolala-tech/page-spy-api@latest && page-spy-api
  

启动完成后，打开浏览器访问 http://localhost:6752 体验，本地测试完成后即可部署到服务器上。

最后

PageSpy 在 Web / 小程序 / ReactNative / OpenHarmony 平台上都已经有稳定的 SDK ，希望 PageSpy 能够帮助到大家！

[sentinelK]

试用了一下，挺有意思。
全力滚动的情况下（最大化的造成画面动作） 10 秒钟 400KB ，也不是很大。
同时记录屏幕效果、鼠标轨迹、事件、控制台、网络、存储。

很有意思的一种行为记录尝试。

但有几个疑问（抱歉没时间通读 readme ）：
1 、我看官方的反馈组件，是没有暂停、停止等录制控制的。那么最长支持录制多长时间？（换句话说录制的内容是暂存在哪里的？如果突破了上限怎么办？是滚动录制，还是？）
2 、在 SDK 中是否支持自定义的反馈组件，或者通过调用 SDK 方法等形式拿到.json ？（比如我想实现静默自动 10 秒上传）
3 、基于成本等原因，我想只记录一部分信息或者调整信息质量（比如录屏的画质、帧率，甚至不需要录屏），目前是否支持。

[sentinelK]

btw:原来开源背景是货拉拉……怪不得如此成熟。

[superliy]

不错

[DreamingCTW]

官网进不去？我自己的网络问题吗？

[cloverstd]

@DreamingCTW #4 托管在 GitHub Pages

[blucas01]

@sentinelK

- "10 秒钟 400 KB"，是因为页面加载过程中请求了一些 shiki 的代码高亮文件，响应数据比较大（记录在网络请求里）；
- "最长支持录制多长时间"，没有限制；
- "录制的内容是暂存在哪里"，默认在内存中放 10M 数据，超过了 10M 写到临时文件（ object url ）；录制的内容在每次操作上传 / 下载后，会清空数据并从当前继续录制（第一次导出的文件 400 kb ，第二次点击导出可能就 50 kb ）；
- "是否支持自定义"，完全支持，操作日志文件提供了 API ；
- "只记录一部分信息"，支持；
- "调整信息质量"，用户操作轨迹是通过记录 DOM 、回放 DOM 来实现的，所以不用担心

[zzNaLOGIC]

年中的时候在公司推过一波了，确实好用。但是的但是，还是有一些注意点的
-对于页面内容的录制，如果是内嵌 iframe 加载的操作页面，会存在 iframe 内部内容无法记录的问题。需要折腾修改一下，好在不麻烦
-对于请求很频繁的页面，长时间监控和记录的情况下，会出现较为严重的性能问题（尤其是低性能电脑上，客户电脑环境不可控），现在已经很多人反馈有浏览器卡顿、延迟的问题了，十分建议不要把单次录制时间拉太长
-应该很多人都会像我一样，第一反应就是二开一下，加个监控指定接口或者报错就自动上传日志的功能吧。可以做，但强烈建议加上频率阈值限制，否则也会导致第二点的性能问题。

[express]

记得好久之前是不是也有个类似的工具叫 find bug 还是 fire bug ，搜了一圈没搜到...

[youyouzi]

有宣发的 PPT 吗？刚好可以做个内部分享 。嘿嘿嘿

[blucas01]

@zzNaLOGIC #7 初始化的时候通过 dataProcessor 参数处理数据（修改、忽略过滤），就可以实现你的需求。比如：

- 忽略掉（不收集）埋点的网络请求；
- 数据中存在敏感信息的话，对数据脱敏；
- ……

也就是：PageSpy 会先把数据处理好 -> 你通过 dataProcessor 自定义数据该如何处理 -> 处理后的数据再交给 PageSpy ，对于你说的频率，也可以自行控制。

[blucas01]

@express 找不到就暂时不纠结了吧，PageSpy 值得你一试 😁

[blucas01]

@zzNaLOGIC dataProcessor 的使用方式可以参考： https://www.pagespy.org/#/docs/changelog#v1_9_2 / https://github.com/HuolalaTech/page-spy/pull/106

[blucas01]

@youyouzi #9 PPT 不好直接丢出来，我整理了 PPT 可以用上的素材： https://static.jikejishu.com/pagespy/frame.svg

[yaocai321]

提问，跟 Sentry 的 replays 比较起来，有什么优势呢。
replays 还只是 Sentry 其中一个能力。

[blucas01]

@yaocai321 #14 优势在于随着 replay 回放，能看到 Console / Network / Storage 的数据

[rowG]

点进仓库一看原来早已被我 star🤣

[blucas01]

@rowG 优秀优秀 😁

[yaocai321]

@blucas01 #15 replays 也可以呀
可以“借鉴”下

[youyouzi]

@blucas01 感谢。后续有时间整理一下成 PPT

[lollipogo]

好东西，已 star ，赞一个

[artoostark]

欢迎来我们这边也分享分享。

[lzcc]

echart 的图表回放不显示，不知道是不是我一个人的问题

[blucas01]

@lzcc 现在可以了（默认情况下不记录 canvas ，刚刚调整了参数，现在已支持 ❤️）

[z13zvxc]

好东西啊！

[blucas01]

@z13zvxc 直接起飞 er ～

[cheung]

Mark 一下， 值得深入学习

[blucas01]

@cheung 先用起来，慢慢学习

[niub]

很有意思，多谢分享👍

[blucas01]

@niub 感谢支持 ♥️

[smilenceX]

确实有意思，虽然我现在不做前端，不过 star 收藏了先。多谢分享。

[blucas01]

@smilenceX 给你的前端同事推一推 😁

[jellyX]

牛逼牛逼, 晚上试用看看, 谢谢 OP

[blucas01]

@jellyX 就是干！要是遇到问题了可以加群哈，仓库的中文 README 底部有群二维码

[saveai]

是好东西，但是也太太太卡了吧...看回放很卡

[saveai]

另外有的功能如果支持更好，
1.希望有一个设置 id ，或者 key 的标识的地方来识别设备，更好分类管理。主要是 Device ID 会变化。Project 和 title 又不适合这样使用。
2.我不知道现在日志是存放在服务端是怎么存放，希望可以支持自动流上传的方式，直到用户关闭浏览器标签页为止。且不需要自己调用 js 代码上传或者用户点按钮才能上传，否则只能用定时轮询的方式不断上传。
3.希望可以支持设置 logo ，隐藏”复制在线调试链接“这个菜单，原因是放到前台后，不需要把后台的东西展示给普通用户，普通用户只需要保留上传日志的功能就行

[blucas01]

@saveai

1. project / title 就是干这个事情的，你说的不适合具体是指？比如设置 title 为用户名，初始化的时候可能还不知道用户信息，但在获取到用户信息后 PageSpy 可以去更新这个连接的信息，参考 https://www.pagespy.org/#/docs/faq#update-info ;
2. 你说的这个自动上传跟埋点差不多，但 PageSpy 主要设计用于：发现问题、即时解决。所以跟埋点还是有点区别的；
3. logo 可以自定义，隐藏菜单按钮你可以通过设置 css 去操作；