一、前言与背景：

大家好，我是完美句号！欢迎来到 HarmonyOS 5 开发实战系列。本系列致力于为开发者提供实用的技术方案和即拿即用的代码示例，帮助大家快速掌握 HarmonyOS Next 应用开发中的核心功能。

移动端形态多样（H5/小程序/Android/iOS/HarmonyOS），调试环境分散、复现场景复杂，线上问题定位常常耗时。传统做法依赖手机端面板或手工日志，信息碎片化且协作成本高。

在 Web 项目中，vConsole 一度成为手机网页调试的“标配”，可在移动端查看 Console 与 Network。但移动端屏幕受限、信息易截断，复杂问题仍难以还原现场。

在此背景下，PageSpy 以“远程现场”的方式打破局限：统一采集日志、网络、存储与系统信息，在桌面端集中呈现与检索，大幅提升定位与协作效率。

---

二、传统鸿蒙项目开发的困境：

对于做前端开发的小伙伴来说，vConsole 几乎已成为“标配”，无论是开发 H5 页面还是小程序，大家几乎都会在项目中集成。

在平时工作中，我们经常需要定位 Bug 与差异性问题，这往往是最耗时、最费精力的环节（不同业务的平台表现形式各异，调试方式也有所差异）：

• ①. 在系统开发过程中，测试同学需要进行线上回归测试，并在 iOS、Android、HarmonyOS 等不同环境下重复验证。
• ②. 系统上线后，客户在使用过程中发现 Bug，需要在测试环境复现，且常常依赖客户充分配合才能还原现场。

另外，在处理线上 Bug 的较优复现方案是：在本地开启开发环境、获取用户登录 token 或 cookie 等凭证，并按照用户反馈的路径进行复现。此法效率较高，但真实场景中用户不一定愿意或能够配合提供验证码、登录凭证等：

• ①. 手动录屏的方式：让用户录制一个视频，开发人员据此判断问题。简单问题或可解决，复杂问题仍需白名单方式深入验证。
• ②. 白名单的方式：设置白名单后模拟用户环境，登录到该用户的手机号码并按业务路径操作复现。

---

三、鸿蒙 PageSpy 远程调试神器介绍：

@huolala/page-spy-harmony 是货拉拉开源项目 PageSpy 在 HarmonyOS 端的实现，用于本地与远程调试用户设备。它集成日志、网络请求、数据存储与系统信息等能力，是一个多功能、可落地的在线调试平台。

项⽬集成 @huolala/page-spy-harmony 后，配合 PageSpy 开箱即⽤的调试端，开发者可以实时观察程序的⽇志、⽹络请求、存储数据的变化，⽅便快速定位问题，保障应⽤质量，极⼤提升⻚⾯调试效率。

任何无法在本地使用控制台调试的场景，都可以使用 PageSpy 来大显身手的时候！一起来看下面的例子：

• ①. 本地调试 H5、Webview 应用：以往有些产品提供了可以在 H5 上查看信息的面板，但移动端屏幕太小操作不便、显示不友好，以及信息被截断等问题。
• ②. 远程办公、跨地区协同：传统沟通方式如邮件、电话、视频会议等，沟通效率不高、故障信息不全面，容易误解误判。
• ③. 用户终端上出现白屏问题：传统定位问题的方式包括数据监控、日志分析等，这些方式依赖排障人员要理解业务需求场景、技术实现。

PageSpy 是一款用于调试 Web/小程序/HarmonyOS App 等平台项目的工具，基于对原生 API 的封装，它将调用原生方法时的参数进行过滤与转化，整理成结构化消息供调试端消费；调试端收到数据后，提供类控制台的交互能力，使复杂场景的调试更直观、更高效。

以下为相关的链接：

鸿蒙三方库PageSpy地址：https://ohpm.openharmony.cn/#/cn/detail/@huolala%2Fpage-spy-harmony@huolala%2Fpage-spy-harmony

Gitee PageSpy地址：https://gitee.com/pagespy/page-spy-web

---

四、鸿蒙三方库“PageSpy”的安装与使用：

为了数据安全和方便您的使用，我们提供完整的、开箱即用的多种部署方案，各位开发者可以根据自己的情况选择任意一种部署方式：一种是Node环境部署，一种是Docker容器化部署。

4.1 Node环境部署：

由于本人更熟悉 Yarn 包管理工具，此处演示 Node 环境部署；熟悉 Docker 的同学可选择容器化部署到服务器。

yarn global add @huolala-tech/page-spy-api@latest
# 如果你使用 npm
npm install -g @huolala-tech/page-spy-api@latest

安装完成之后，可以在命令行中直接执行 page-spy-api 启动服务，启动完成后，会检测本机有多个IP地址，可以选择一个合适的链接，当然，如果是服务器上的话，建议使用PM2来管理后台服务，这样可以保证后台服务的稳定性。

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

---

4.2 在需要使用的 har/hsp 模块中，通过ohpm安装三方库“page-spy-harmony”：

在确定上面ohpm安装成功可以查看版本后，我们通过ohpm命令来执行如何在项目中引入三方库，执行以下命令：

ohpm install @huolala/page-spy-harmony

我们这里可以看到，安装三方库“page-spy-harmony”成功后，通过查看“oh-package.json5”文件中的版本为"^2.1.0"，说明三方库安装成功。

以下为 API 9/11/16 的兼容性说明：

• @huolala/page-spy-harmony@1.x：基于 API 9 版本开发。
• @huolala/page-spy-harmony@2.0.x：基于 API 11 版本开发。
• @huolala/page-spy-harmony@2.1.x：基于 API 16 版本开发(推荐使用)。

---

4.3 在项目中引入三方库“page-spy-harmony”并使用：

在合适的位置引入 SDK 并初始化，这里以 EntryAbility 为例，初始化参数提供了可选的 配置项 用于自定义 SDK 的行为：

import { PageSpy } from '@huolala/page-spy-harmony';
import axiosInstance from 'path/to/your/axios-instance'; // 如果你项目中使用了axios，请传入你的实例，需要修改你对应的路径

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    new PageSpy({
      context: this.context,
      api: "192.168.10.159:6752",
      enableSSL: false,  // 这里要改为false，因为本地调试用的是http协议，不是https协议
      axios: axiosInstance
    })
  }
}

这里发现，我们使用的是axiosInstance的实例对象，但我们项目是以"@kit.NetworkKit"模块来进行封装，所以这里需要先封装一个axios实例对象。

//导入模块
import {http} from "@kit.NetworkKit"
 
//封装http请求
class httpServer {
  //设置一个变量，当你创建实例时传入你项目的baseURL
  private baseURL:string=""
  constructor(baseURL:string) {
    this.baseURL=baseURL
  }  
  
  //一些请求头常量，根据要求修改
  private AppId:string="你项目一些识别应用的ID"
  private AppKey:string="根据需求传入"
  private mastKey:string="根据需求传入"
  
  // get请求方法（url必传，传进来自动与 baseURL 拼接；当需要传后面的可选参数时，前面的可选参数传空）
  get(url:string, params?:string, masterKey?:string, token?:string,){
    const httpRequest=http.createHttp();  //构建一个http请求实例
    console.log(url,params,masterKey,token) //可以查看你传入的东西符不符合预期
    return httpRequest.request(this.baseURL+url,{    //发起http请求，返回promise
      method:http.RequestMethod.GET,  //请求方式
      extraData:params?JSON.parse(params):null,  //参数
      header:{   //请求头
        'X-LC-Id': this.AppId,  
        'X-LC-Key':masterKey?masterKey+",master":this.AppKey, 
        'Content-Type': 'application/json',
        "X-LC-Session":token?token:null,
      }
    })
  }
 
  //post请求方法
  post(url:string,params?:string,masterKey?:string,token?:string){
    const httpRequest=http.createHttp();
    console.log(url,params,masterKey,token)
    return httpRequest.request(this.baseURL+url,{  //和你传入的url做拼接
      method:http.RequestMethod.POST,
      extraData:params?JSON.parse(params):null,
      header:{
        'X-LC-Id': this.AppId,
        'X-LC-Key': masterKey?masterKey+",master":this.AppKey,
        'Content-Type': 'application/json',
        "X-LC-Session":token?token:null
      }
    })
  }
 
  //put请求方法
  put(url:string,sessionToken?:string,params?:string){
    const httpRequest=http.createHttp();
    return httpRequest.request(this.baseURL+url,{
      method:http.RequestMethod.PUT,
      extraData:JSON.parse(params),
      header:{
        'X-LC-Id': this.AppId,
        'X-LC-Key': this.AppKey,
        'Content-Type': 'application/json',
        "X-LC-Session":sessionToken?sessionToken:null
      }
    })
  }
 
  //delete请求
  delete(url:string,params?:string,masterKey?:string){
    console.log(url,params,masterKey)
    const httpRequest=http.createHttp();
    return httpRequest.request(this.baseURL+url,{
      method:http.RequestMethod.DELETE,
      extraData:params?JSON.parse(params):null,
      header:{
        'X-LC-Id':this.AppId,
        'X-LC-Key': masterKey?masterKey+",master":this.AppKey,
      }
  })
}

export default httpServer;

以上就是在鸿蒙 App 项目中接入 PageSpy 的全部流程，接入完成后点击 PageSpy服务端 顶部的菜单 "开始调试" 使用，项目接入PageSpy 后，可以在页面列表，看到如下的页面：

---

五、总结：

PageSpy 是一款强大的远程调试工具，能帮助开发与测试快速定位与优化。对于生产环境中难以复现的问题，PageSpy 通过远程采集与集中呈现，显著缩短排查时间并提升协作效率。

在运行的过程中，可以发现，在鸿蒙 App 项目中接入 PageSpy 非常简单，只需要几个步骤就可以完成。同时，PageSpy 也提供了丰富的功能，如网络请求监控、日志查看、缓存管理等，可以帮助开发和测试人员更好地调试和优化系统。

PageSpy能够整理出规范化的消息数据供调试端高效消费，类似于本地控制台的操作界面，使复杂场景的调试变得直观和高效，从而提高开发效率，无论是何种无法在本地使用控制台进行调试的复杂场景，PageSpy都能轻松应对。

---

八、与 vConsole 对比分析：

针对常见的移动端调试面板 vConsole，从连接方式、采集维度、协作效率等多个维度对比 PageSpy 的优势与适用场景。

维度	PageSpy	vConsole
连接方式	远程调试端采集用户设备数据	内嵌面板在手机端查看
数据采集	日志、网络、Storage、系统信息多维采集	以 Console/Network 为主
使用体验	大屏端交互、检索、批量导出	小屏查看，操作受限
协作效率	支持跨地域远程协同、还原用户现场	依赖用户手动录屏/复现
部署成本	需服务端部署（Node/Docker/PM2）	无服务端，嵌入成本低
安全策略	支持域名/SSL、访问控制与隔离	受前端接入方式限制