前端开发工具调试器【免费下载链接】page-spy-webA remote debugging platform youll definitely find useful. Lightweight, cross-platform, out-of-box debugging tool项目地址https://gitcode.com/gh_mirrors/pa/page-spy-web点击查看免费下载本文基于当前仓库中的 README_JA.md与 README_ZH.md 同源编写面向 Web、React Native、小程序、HarmonyOS 等多端项目的开发者帮助你理解 PageSpy 的远程调试原理、典型适用场景并掌握 Node.js 与 Docker 两种开箱即用的自托管部署方式。读完本文你将能够独立完成 PageSpy 服务端的安装、启动、配置与常见问题排查。PageSpy 是什么为本地控制台无能为力的场景而生PageSpy是一款用于调试 Web、React Native、小程序、HarmonyOS 应用等跨平台项目的开源远程调试工具。它的核心设计是对客户端原生 API 做一层封装——当页面调用console、网络请求、本地存储等方法时SDK 会在方法实际执行前对入参进行过滤与转换再按统一格式序列化通过 WebSocket 发送给调试端调试端收到数据后以接近本地开发者工具DevTools控制台的界面直观呈现出来。这一封装原生 API → 序列化 → 实时传输 → 调试端可视化的链路正是 PageSpy 与普通日志上报类工具的本质区别它不是事后看日志而是把本地调试的体验搬到远程。调试端具备哪些面板能力从仓库中的官方文档 introduction.zh.mdx 可以看到PageSpy 在提供调试功能的基础上扩展出在线实时调试与离线日志回放两大场景其中在线实时调试包含五个核心面板Console 面板显示console.log | info | warn | error | debug输出的日志信息并支持向客户端发送代码、远程执行Network 面板显示客户端发出的网络请求信息ElementPage面板显示客户端当前界面可查看 HTML 节点树Storage 面板查看客户端本地的缓存数据Cookie、LocalStorage 等System 面板显示客户端系统信息辅助排查兼容性问题。当有新数据产生或数据发生变化时调试端会实时收到通知。此外配合 DataHarborPlugin 与 RRWebPlugin 两个插件还可以实现离线日志回放像看录像一样重现用户操作轨迹与当时的运行数据详见 offline-log.zh.mdx。源码侧的支撑从仓库结构看page-spy-web 同时承载调试端前端与服务端两个角色前端调试界面位于 src/pages/DevtoolsConsole、Network、Element、Storage、System 各面板路由定义见 src/routes/config.tsx服务端入口位于 backend/main.go通过embed.FS将构建产物dist内嵌进 Go 二进制然后调用serve.Run()启动 HTTP 与 WebSocket 服务服务端依赖 backend/go.mod 中声明的github.com/HuolalaTech/page-spy-api v1.11.0作为核心运行库。何时使用 PageSpy三类典型场景凡是无法在本地使用控制台调试的场景都是 PageSpy 可以大显身手的时候。原文档列举了三类典型场景本地调试 H5、WebView 应用移动端屏幕太小传统调试面板操作不便、显示不友好且日志容易出现截断远程办公、跨地区协同邮件、电话、视频会议等传统沟通方式效率低故障信息不完整容易产生误解或误判用户终端白屏等问题排查数据监控、日志分析等传统手段依赖排障人员对业务和技术的深入理解在用户设备上收窄问题原因通常很慢。PageSpy 正是面向存在上述问题的团队而打造其目标是把调试能力下沉到任何一台能打开浏览器的终端上。快速开始一使用 Node.js 部署为了让数据掌握在自己手中并降低自建部署门槛PageSpy 提供了多种开箱即用的部署方式。第一种是全局安装 NPM 包huolala-tech/page-spy-api# 使用 yarn yarn global add huolala-tech/page-spy-apilatest # 使用 npm npm install -g huolala-tech/page-spy-apilatest安装完成后在终端执行page-spy-api启动服务。服务就绪后在浏览器中打开http://localhost:6752即可访问调试端。本地验证通过后可将同一套部署推送到你的服务器。仓库内的官方安装文档 deploy-with-node.zh.mdx 给出了等价的写法yarn global add huolala-tech/page-spy-apilatest page-spy-api。从源码看 NPM 包的二进制分发机制huolala-tech/page-spy-api并非一个普通的 JS 包它通过optionalDependencies按平台分发编译好的原生可执行文件。这一点在 package.json 中可见一斑huolala-tech/page-spy-api被声明在optionalDependencies中版本与仓库版本同步为2.4.9。具体机制体现在 backend/publish/install.js根据process.platform os.arch() os.endianness()匹配当前平台支持win32-arm、win32-arm64、win32-x64amd64、darwin-arm64、darwin-x64、linux-arm、linux-arm64、linux-x64等平台组合分别对应page-spy-api-win32-arm、page-spy-api-linux-amd64等独立子包如果用户以--no-optional安装导致平台二进制缺失安装脚本会先尝试用 npm 安装对应平台包失败后再直接从 npm registry 下载.tgz并解压出二进制downloadDirectlyFromNPM脚本还针对中文环境做了优化当LANG以zh_CN开头时会优先从https://registry.npmmirror.com源安装失败后自动回退到官方源。而 backend/publish/page-spy-api.js 则是一个 shim 启动器它定位到当前平台的二进制路径然后用execFileSync以继承 stdio 的方式执行真正的二进制把命令行参数原样透传——这就是全局安装后page-spy-api命令能直接工作的原因。快速开始二使用 Docker 部署如果你更倾向容器化部署可以直接拉取官方镜像docker run -d --restartalways -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --namepageSpy ghcr.io/huolalatech/page-spy-web:latest逐项拆解这条命令的参数含义参数作用-d后台运行容器--restartalways容器异常退出后自动重启-v ./log:/app/log将宿主机./log目录映射到容器的/app/log持久化日志数据-v ./data:/app/data将宿主机./data目录映射到容器的/app/data持久化数据库等数据-p 6752:6752将容器 6752 端口映射到宿主机 6752 端口--namepageSpy指定容器名称容器运行后在浏览器中打开http://localhost:6752。注意如果容器被销毁未映射到宿主机的数据也会一并丢失因此务必保留-v的目录映射详见 faq.zh.mdx 中关于离线日志持久化的说明。从 Dockerfile 看镜像结构仓库根目录的 Dockerfile 采用两阶段构建构建阶段基于golang:1.23先下载backend/go.mod、backend/go.sum声明的依赖再以CGO_ENABLED0 GOOSlinux交叉编译出静态二进制main静态编译意味着镜像无需携带动态库体积更小、更易分发运行阶段基于alpine:latest仅将编译好的/app/main拷入并以/app/main作为启动命令——这与 backend/main.go 中内嵌 dist 前端产物、单一二进制启动的设计完全吻合。因此Docker 镜像本质上就是Go 服务端二进制 内嵌前端页面的合体一个镜像即可提供完整的调试平台。部署后的服务端配置config.jsonPageSpy 服务端在运行时自动读取当前运行目录下的config.json配置文件。该文件在初次运行时并不存在你可以根据需要创建或修改它来自定义服务端行为可配置内容包括运行端口、多实例部署、跨域配置、日志数据配置、数据库配置等。完整字段说明见 server-configuration.zh.mdx这里给出带注释的完整示例{ // 服务端口 port: 6752, // 日志回放文件最大大小MB maxLogFileSizeOfMB: 10240, // 日志回放文件最长保存时间小时 maxLogLifeTimeOfHour: 720, // 是否允许用户在界面上删除日志 notAllowedDeleteLog: false, // 最大允许房间数量 maxRoomNumber: 500, // 跨域配置 corsConfig: { // 允许的域名 allowOrigins: [*], // 允许的请求头 allowHeaders: [ Origin, Authorization, Content-Length, X-Request-Id, Content-Type, Referer, User-Agent, Host ], // 允许的请求方法 allowMethods: [ HEAD, POST, GET, OPTIONS, PUT, DELETE, UPDATE ], // 暴露的请求头 exposeHeaders: [X-Request-Id] }, // 符合 S3 协议的存储配置 storageConfig: { baseDir: , keyId: , secret: , bucket: , region: , endpoint: , // s3ForcePathStylefalse 表示 virtual-hosted-style API默认情况 // s3ForcePathStyletrue 表示 path-style API s3ForcePathStyle: false }, // 认证配置 authConfig: { // 认证密码 password: , // JWT 密钥 jwtSecret: , // 令牌过期时间小时 tokenExpiration: 720 }, // 多实例部署时配置为当前机器 IP 或容器中的 DNS name selfRpcAddress: { ip: , port: }, // 多实例部署配置 rpcAddress: [ { ip: , port: }, { ip: , port: } ], // 配置 MySQL 数据库地址默认使用 SQLite databaseConfig: { mysqlUrl: user:passtcp(127.0.0.1:3306)/dbname?charsetutf8mb4parseTimeTruelocLocal } }几个值得注意的要点存储与数据库默认使用 SQLite 本地存储对应依赖见 backend/go.mod 中的modernc.org/sqlite、glebarez/sqlite配置databaseConfig.mysqlUrl后可切换为 MySQL对应gorm.io/driver/mysql。离线日志文件默认保存在运行目录的log目录下。认证保护从 2.3.0 版本起PageSpy 支持通过环境变量为调试端设置访问密码与authConfig对应的环境变量为AUTH_PASSWORD、JWT_SECRET、JWT_EXPIRATION_HOURSToken 过期时间默认 24 小时。设置密码后开发者访问调试面板必须输入正确密码。启动方式为# Docker 方式 docker run -d --restartalways -v ./log:/app/log -v ./data:/app/data -p 6752:6752 --namepageSpy \ -e AUTH_PASSWORDpassword -e JWT_SECRETsecret -e JWT_EXPIRATION_HOURShours \ ghcr.io/huolalatech/page-spy-web:latest # Node 方式 AUTH_PASSWORDpassword JWT_SECRETsecret JWT_EXPIRATION_HOURShours page-spy-api日志容量控制默认最多保存最新 10GB、最长 30 天即maxLogFileSizeOfMB: 10240与maxLogLifeTimeOfHour: 720可通过修改配置自定义。客户端如何接入以浏览器为例部署好服务端后即可在客户端项目中接入 SDK。以浏览器为例完整说明见 browser.zh.mdx通过script引入时 SDK 会自动从引入路径分析服务端地址!-- PageSpy SDK -- script crossoriginanonymous src{deployUrl}/page-spy/index.min.js/script !-- 插件非必须但建议使用 -- script crossoriginanonymous src{deployUrl}/plugin/data-harbor/index.min.js/script script crossoriginanonymous src{deployUrl}/plugin/rrweb/index.min.js/script script window.$harbor new DataHarborPlugin(); window.$rrweb new RRWebPlugin(); [window.$harbor, window.$rrweb].forEach(p { PageSpy.registerPlugin(p) }) window.$pageSpy new PageSpy(); /script其中DataHarborPlugin用于缓存离线日志并提供上传/下载能力离线回放的基础RRWebPlugin基于 rrweb 记录用户操作轨迹两者通常配合使用。小程序WeChat / Alipay / UniApp / Taro、React Native、HarmonyOS 也都有对应的 SDK 包与接入流程分别见 miniprogram.zh.mdx、react-native.zh.mdx、harmony.zh.mdx。关于实例化参数如api、clientOrigin、enableSSL、useSecret、gesture、disabledPlugins等的完整说明可查阅 pagespy.zh.mdx 中的 PageSpy API 文档。常见问题与运维要点服务器上 6752 端口访问不通检查服务器防火墙或安全组规则是否放行了 6752 端口参考 faq.zh.mdx。调试按钮提示当前连接不存在客户端通常意味着 SDK 已创建房间但无法通过 WebSocket 加入可打开客户端控制台查看是否出现WebSocket connect failed相关报错据此检查服务端配置。Nginx 反向代理需要显式开启 WebSocket 升级支持location / { proxy_pass http://127.0.0.1:6752; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; }部署到子路径1.5.4 版本起支持子路径部署除调整 Nginx 的rewrite规则外实例化时需要手动传参window.$pageSpy new PageSpy({ api: host/sub-path, // 例如 api: example.com/pagespy clientOrigin: scheme://host/sub-path, // 例如 https://example.com/pagespy });升级到最新版本Docker 方式先docker pull ghcr.io/huolalatech/page-spy-web:latest再停止并删除旧容器后重新docker runNPM 方式执行yarn global upgrade huolala-tech/page-spy-apilatest或npm install -g huolala-tech/page-spy-apilatest后重启进程。房间生命周期从服务端实现看房间在创建后无 SDK 或调试端进入 1 分钟、SDK 与调试端均已断开 1 分钟、长时间无数据交互 5 分钟以及连接持续超过 1 小时等条件下会被自动销毁。参与贡献与延伸阅读PageSpy 采用 MIT 协议开源见 LICENSE。如果你想参与贡献可以阅读仓库的 CONTRIBUTING_ZH.md英文版见 CONTRIBUTING.md。进一步了解模块组成、兼容性、权限认证、插件机制等细节推荐继续阅读仓库内的官方文档常见问题FAQ服务端配置说明离线日志回放插件开发指南PageSpy API 文档赞分享前端开发工具调试器【免费下载链接】page-spy-webA remote debugging platform youll definitely find useful. Lightweight, cross-platform, out-of-box debugging tool项目地址https://gitcode.com/gh_mirrors/pa/page-spy-web点击查看免费下载相关推荐PageSpy 远程调试平台架构原理与 Node.js、Docker 一键部署实战PageSpy 远程调试平台架构原理与 Node.js、Docker 一键部署实战 本文以 page spy web 仓库的 README 为核心脉络系统梳前端开发工具调试器5分钟快速上手PageSpy从安装到调试的完整流程5分钟快速上手PageSpy从安装到调试的完整流程 想要像Chrome开发者工具一样远程调试你的Web应用吗PageSpy就是你的终极解决方案这个强大的前前端开发工具调试器AppCut容器化部署终极指南从零到一快速上手Docker部署AppCut容器化部署终极指南从零到一快速上手Docker部署 AppCut作为开源视频编辑工具通过Docker容器化部署可以快速搭建完整的视频处理环境。本音视频前端桌面应用上一篇Windows安卓应用安装指南告别笨重模拟器的终极解决方案下一篇FoundationDB 8.0 版本发布全解析API 800、Native CDC 与备份体系重构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
