《深入 PageSpy》二：入门指南

本指南提供了安装、配置和部署 PageSpy 用于远程调试的逐步说明。

系统要求

在安装 PageSpy 之前，请确保您的环境满足以下要求：

Node.js：v14.0.0 或更高版本（用于 Node.js 部署）
Docker：最新稳定版本（用于 Docker 部署）
Web 浏览器：Chrome，Firefox，Safari 或 Edge（建议使用最新版本）
操作系统：Windows，macOS 或 Linux

安装选项

PageSpy 提供两种主要安装方法：Node.js 和 Docker，选择最适合您环境的选项。

Node.js 安装

使用 Node.js 安装 PageSpy：

perl 复制代码

# 使用 npm
npm install -g @huolala-tech/page-spy-api@latest

# 使用 yarn
yarn global add @huolala-tech/page-spy-api@latest

安装完成后，启动 PageSpy 服务：

复制代码

page-spy-api

该服务将在 http://localhost:6752 提供。

Docker 安装

使用 Docker 安装 PageSpy：

bash 复制代码

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（-d）
设置自动重启（--restart=always）
挂载日志和数据卷
将端口 6752 映射到主机
将容器命名为 "pageSpy"

该服务将在 http://localhost:6752 提供。

将 SDK 集成到您的程序中

部署 PageSpy 服务器后，您需要将适当的 SDK 集成到目标应用程序中。

Web 应用集成

对于 Web 应用程序，请安装浏览器 SDK：

bash 复制代码

npm install @huolala-tech/page-spy-browser

然后将以下代码添加到您的应用程序中：

javascript 复制代码

import PageSpy from '@huolala-tech/page-spy-browser';

new PageSpy({
  api: '<your-pagespy-server>',
  clientOrigin: '<schema>://<your-pagespy-server>'
});

小程序集成

PageSpy 支持各种小程序框架：

微信小程序:

bash 复制代码

npm install @huolala-tech/page-spy-wechat

支付宝小程序:

bash 复制代码

npm install @huolala-tech/page-spy-alipay

UniApp:

bash 复制代码

npm install @huolala-tech/page-spy-uniapp

Taro:

bash 复制代码

npm install @huolala-tech/page-spy-taro

集成模式在所有 SDK 中都是相似的：

javascript 复制代码

import PageSpy from '@huolala-tech/page-spy-[platform]';

new PageSpy({
  api: '<your-pagespy-server>'
  enableSSL: false, // 默认 true
});

HarmonyOS 集成

针对 HarmonyOS 应用程序：

bash 复制代码

npm install @huolala/page-spy-harmony

按照下面的代码进行集成：

scala 复制代码

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-server>",
      enableSSL: true,
      axios: axiosInstance
    })
  }
}

远程调试过程

一旦您部署了 PageSpy 并将 SDK 集成到您的应用程序中，远程调试过程将按如下方式进行：

使用 PageSpy 界面

安装 PageSpy 并集成 SDK 后，请按照以下步骤开始调试：

打开 PageSpy Web 界面:
1. 导航到您的 PageSpy 服务 URL（例如， http://localhost:6752 ）
选择调试模式:
1. 选择"房间列表"查看可用的实时连接
2. 选择"日志列表"查看记录的离线日志
连接到目标应用程序：
1. 对于实时调试，请从房间列表中选择一个房间
2. 对于日志回放，请从日志列表中选择一个日志
使用 DevTools 面板:
1. 日志：查看日志并执行 JavaScript
2. 网络：检查网络请求和响应
3. 存储：检查 cookies、localStorage 和 sessionStorage
4. 查看系统信息
5. 页面：检查页面结构、检查 DOM 元素

高级功能

PageSpy 包括几个插件，扩展了其功能：

数据港：启用离线记录和存储

kotlin 复制代码

npm install @huolala-tech/page-spy-plugin-data-harbor

rrweb：启用会话录制和回放

bash 复制代码

npm install @huolala-tech/page-spy-plugin-rrweb

O-Spy：提供简化集成

bash 复制代码

npm install @huolala-tech/page-spy-plugin-ospy

要使用这些插件，请将它们与主 SDK 一起安装，并按照集成说明进行操作。

常见问题的故障排除

安装问题

如果您在安装 Node.js 时遇到问题：

确保您拥有正确的 Node.js 版本（14+）
尝试在 macOS/Linux 上使用 sudo 进行全局安装
检查冲突的软件包或路径问题

关于 Docker 安装问题：

验证 Docker 是否正在运行
检查 6752 端口上的端口冲突
确保正确的卷挂载权限

连接问题

如果目标应用程序无法连接到 PageSpy：

验证 PageSpy 服务器是否正在运行
检查应用程序和服务器之间的网络连接
确保在 SDK 初始化中提供了正确的服务器 URL
验证没有防火墙或代理阻止连接

SDK 集成问题

如果您在 SDK 集成方面遇到问题：

检查您是否在使用适合您平台的正确 SDK
在任何应用程序代码之前，请验证 SDK 是否已正确初始化
检查浏览器控制台是否有与 PageSpy 初始化相关的错误

Next Steps 下一步

成功安装和设置 PageSpy 后：

探索 DevTools 界面，熟悉可用功能
配置额外的插件以获得增强功能
为团队使用设置持久化部署
查看 PageSpy 文档以获取高级用法

有关 PageSpy 各方面更详细的信息，请参阅：

理解 PageSpy 整体结构的架构
用于了解调试界面的 DevTools UI
用于高级部署配置的部署选项