一、服务端部署方案

1.1 私有化部署路径

推荐采用私有化部署方案保障数据安全，主流部署方式包含以下三种：

Node环境部署：基于Node.js运行时构建服务，适合已有Node基础设施的团队。需下载官方提供的服务端包，通过npm install安装依赖后，使用node server.js启动服务。
容器化部署：通过Docker镜像实现快速部署，支持横向扩展。使用docker pull pagespy/server拉取镜像，通过docker run -d -p 6752:6752 pagespy/server命令启动容器。
可视化面板部署：针对无技术背景的运维人员，提供宝塔面板插件，通过图形化界面完成服务配置与启动。

1.2 免部署应急方案

对于临时调试需求，可采用CDN直接引入方案（生产环境慎用）：

<script src="https://cdn.example.com/libs/o-spy/2.2.9/index.min.js" crossorigin="anonymous"></script>
<script>
  const $oSpy = new OSpy({
    api: 'https://your-server:6752', // 指定后端服务地址
    autoRender: true // 自动显示调试图标
  });
</script>

该方案将调试数据通过WebSocket直连指定服务端，存在数据泄露风险，建议仅在测试环境使用。

二、客户端集成方案

2.1 CDN集成模式

适用于传统Web项目，通过动态加载脚本实现无侵入集成：

<!-- 核心库 -->
<script crossorigin="anonymous" 
        src="https://your-domain/page-spy/index.min.js">
</script>
<!-- 插件扩展（可选） -->
<script crossorigin="anonymous" 
        src="https://your-domain/plugin/data-harbor/index.min.js">
</script>
<script crossorigin="anonymous" 
        src="https://your-domain/plugin/rrweb/index.min.js">
</script>
<script>
  // 插件初始化
  const plugins = [
    new DataHarborPlugin(),
    new RRWebPlugin()
  ];
  // 注册插件
  plugins.forEach(p => PageSpy.registerPlugin(p));
  // 创建实例
  const pageSpy = new PageSpy({
    clientOrigin: window.location.origin,
    enableSSL: false,
    maxRecords: 1000 // 限制最大记录数
  });
</script>

2.2 模块化集成方案

针对现代前端框架（React/Vue等），推荐使用ESM模块导入：

# 安装依赖
yarn add @framework/page-spy-browser \
         @framework/page-spy-plugin-data-harbor \
         @framework/page-spy-plugin-rrweb

// TypeScript集成示例
import PageSpy from '@framework/page-spy-browser';
import DataHarbor from '@framework/page-spy-plugin-data-harbor';
import RRWeb from '@framework/page-spy-plugin-rrweb';
// 插件配置
const config = {
  api: 'wss://your-server:6752',
  autoRender: false,
  samplingRate: 0.5 // 设置50%采样率
};
// 初始化逻辑
const initPageSpy = () => {
  const harbor = new DataHarbor();
  const rrweb = new RRWeb({ recordCanvas: true });
  const spy = new PageSpy(config);
  [harbor, rrweb].forEach(spy.registerPlugin);
  // 手动触发渲染
  document.addEventListener('dblclick', () => {
    spy.render({ position: 'bottom-right' });
  });
  return spy;
};
export default initPageSpy;

三、核心功能扩展

3.1 插件生态系统

系统提供三大核心插件：

DataHarbor：实现调试数据持久化存储，支持历史数据回溯分析
RRWeb：基于DOM快照的完整用户行为录制，支持时间轴回放
Performance：集成Performance API，自动捕获页面性能指标

插件注册机制采用观察者模式，支持自定义插件开发：

class CustomPlugin {
  constructor() {
    this.events = ['click', 'scroll'];
  }
  install(spy) {
    this.events.forEach(event => {
      spy.on(event, this.handleEvent.bind(this));
    });
  }
  handleEvent(payload) {
    console.log('Custom event:', payload);
  }
}
// 注册自定义插件
PageSpy.registerPlugin(new CustomPlugin());

3.2 高级配置选项

参数	类型	默认值	说明
api	string	-	后端服务地址
autoRender	boolean	false	自动显示调试图标
maxBufferSize	number	5000	客户端缓存上限
networkThrottle	number	200	网络请求采样间隔(ms)
enableSSL	boolean	false	强制HTTPS连接

四、调试工作流程

4.1 激活调试模式

通过以下任一方式激活调试界面：

手势触发：连续快速点击页面5次（可配置）
快捷键触发：按下Ctrl+Shift+D组合键
代码触发：调用window.$pageSpy.render()方法

4.2 核心调试面板

激活后显示四类功能模块：

实时监控：展示FPS、内存占用等实时指标
事件流：记录所有用户交互事件的时间轴
网络分析：可视化展示所有网络请求的瀑布流
控制台：支持直接执行JavaScript调试命令

4.3 典型问题诊断

场景1：内存泄漏分析

通过RRWeb插件录制用户操作流程
在Performance面板观察内存增长曲线
结合Heap Snapshot定位内存占用对象

场景2：渲染性能优化

启用Paint Timing标记
在时间轴上识别长任务（Long Task）
使用Layer Borders分析重绘区域

五、生产环境建议

数据安全：配置IP白名单，限制可连接客户端
性能优化：调整samplingRate参数控制数据采集频率
日志管理：集成对象存储服务实现调试日志长期归档
告警机制：通过Webhook对接监控系统，异常时自动通知

通过系统化的部署方案与功能扩展，PageSpy可构建完整的前端可观测性体系。建议开发团队在预发布环境常态化部署，结合自动化测试流程，实现问题早发现、早修复。对于大型项目，可考虑基于插件机制开发定制化诊断模块，满足特定业务场景的调试需求。

前端性能诊断利器：PageSpy部署与调试全流程指南