epoint-m8-debug-tools

v1.1.0

Published

5 months ago

支持H5和微信小程序的调试工具集，集成前端监控功能，基于eruda的强大调试功能

0High
0Medium
0Low

helun940122

debug eruda vconsole miniprogram h5 websocket epoint m8 tools utils

epoint-m8-debug-tools

一个支持 H5 和微信小程序环境的调试工具集成插件，集成前端监控功能。

特性

🌐 多环境支持: 支持 H5、微信小程序和支付宝小程序环境
🔧 H5 调试: 基于 eruda 的强大调试功能
📱 小程序调试: 集成 wx.setEnableDebug 和实时日志管理
🔌 WebSocket 插件: 自定义 WebSocket 请求展示插件
⚙️ 个性化配置: 支持自定义点击次数、入口元素等
📊 错误上报: 支持错误自动上报功能
🎯 TypeScript: 完整的 TypeScript 类型支持
📈 前端监控: 集成控制台、网络请求、错误监控功能
🔐 用户过滤: 支持基于 openId 的用户过滤监控
🎛️ 开关控制: 支持动态启用/禁用监控功能

安装

npm install epoint-m8-debug-tools

快速开始

自动检测环境

import DebugTools from "epoint-m8-debug-tools";

// 自动检测环境并初始化
const debugTools = DebugTools.createAuto({
  clickCount: 5,
  entrySelector: "#debug-entry",
  reportUrl: "https://your-error-report-api.com/report",
});

// 显示调试工具
debugTools.show();

H5 环境使用

import { DebugTools, EnvironmentType } from "epoint-m8-debug-tools";

const debugTools = DebugTools.createH5({
  clickCount: 6,
  entrySelector: "#debug-btn",
  erudaCdn: "https://cdn.jsdelivr.net/npm/eruda@latest/eruda.min.js",
  enableWebSocketPlugin: true,
  webSocketConfig: {
    maxRecords: 1000,
    showHeartbeat: false,
  },
  // 前端监控配置
  monitoring: {
    enabled: true,
    openId: "user-123456", // 用户过滤
    appkey: "h5-app",
    enableConsoleMonitoring: true,
    enableRequestMonitoring: true,
    enableErrorMonitoring: true,
    reportUrl: "https://app.epoint.com.cn/autodeploy/monitor/track/report",
    customData: {
      version: "1.0.0",
      channel: "web",
    },
  },
  reportUrl: "https://api.example.com/error-report",
  reportPrefix: "h5-app",
  reportKey: "message",
  otherReport: {
    userId: "12345",
    version: "1.0.0",
  },
});

// 显示eruda调试面板
debugTools.show();

// 隐藏调试面板
debugTools.hide();

// 监控功能控制
debugTools.enableMonitoring(); // 启用监控
debugTools.disableMonitoring(); // 禁用监控
debugTools.getMonitoringStatus(); // 获取监控状态

微信小程序环境使用

import { DebugTools } from "epoint-m8-debug-tools";

const debugTools = DebugTools.createMiniProgram({
  clickCount: 7,
  realtimeLogConfig: {
    enabled: true,
    level: "info",
  },
  // 前端监控配置
  monitoring: {
    enabled: true,
    openId: "wx-user-123456", // 用户过滤
    appkey: "wx-miniprogram",
    enableConsoleMonitoring: true,
    enableRequestMonitoring: true,
    enableErrorMonitoring: true,
    reportUrl: "https://app.epoint.com.cn/autodeploy/monitor/track/report",
    customData: {
      version: "1.0.0",
      scene: 1001,
    },
  },
  miniProgramType: "wx", // 'wx' | 'alipay'
  reportUrl: "https://api.example.com/mp-error-report",
  reportPrefix: "miniprogram",
  otherReport: {
    openId: "xxx",
    scene: 1001,
  },
});

// 在页面中绑定点击事件
Page({
  onTapDebugEntry() {
    debugTools.triggerEntryClick();
  },

  onShow() {
    // 手动开启调试
    debugTools.show();
  },

  // 监控功能控制
  onTapEnableMonitoring() {
    debugTools.enableMonitoring();
  },

  onTapDisableMonitoring() {
    debugTools.disableMonitoring();
  },

  onTapReportCustomData() {
    debugTools.reportMonitoringData({
      event: "user_action",
      page: "index",
    });
  },
});

API 文档

DebugTools

静态方法

DebugTools.createAuto(config) - 自动检测环境并创建实例
DebugTools.createH5(config) - 创建 H5 环境调试工具
DebugTools.createMiniProgram(config) - 创建小程序环境调试工具
DebugTools.detectEnvironment() - 检测当前环境类型

实例方法

调试功能

show() - 显示调试工具
hide() - 隐藏调试工具
toggle() - 切换调试工具显示状态
triggerEntryClick() - 手动触发入口点击（小程序环境）
getDebugStatus() - 获取调试状态
getLogs() - 获取日志记录
clearLogs() - 清空日志记录

监控功能

enableMonitoring() - 启用前端监控
disableMonitoring() - 禁用前端监控
getMonitoringStatus() - 获取监控状态
updateMonitoringConfig(config) - 更新监控配置
reportMonitoringData(data) - 手动上报监控数据
getMonitoringQueue() - 获取监控任务队列

通用功能

updateConfig(config) - 更新配置
getConfig() - 获取当前配置
destroy() - 销毁调试工具实例

配置选项

基础配置 (BaseConfig)

interface BaseConfig {
  environment: EnvironmentType;
  clickCount?: number; // 点击次数触发调试，默认6次
  entrySelector?: string; // 触发元素选择器
  reportUrl?: string; // 错误上报地址
  reportPrefix?: string; // 错误上报前缀
  reportKey?: string; // 错误上报key，默认'msg'
  otherReport?: Record<string, any>; // 其他上报信息
}

H5 环境配置 (H5Config)

interface H5Config extends BaseConfig {
  environment: EnvironmentType.H5;
  erudaCdn?: string; // eruda CDN地址
  enableWebSocketPlugin?: boolean; // 是否启用WebSocket插件
  webSocketConfig?: {
    maxRecords?: number; // 最大记录数，默认1000
    showHeartbeat?: boolean; // 是否显示心跳包，默认true
  };
}

小程序环境配置 (MiniProgramConfig)

interface MiniProgramConfig extends BaseConfig {
  environment: EnvironmentType.MINIPROGRAM;
  realtimeLogConfig?: {
    enabled?: boolean; // 是否启用实时日志，默认true
    level?: "debug" | "info" | "warn" | "error"; // 日志级别，默认'info'
  };
  monitoring?: MonitoringConfig; // 前端监控配置
  miniProgramType?: "wx" | "alipay"; // 小程序类型
}

前端监控配置 (MonitoringConfig)

interface MonitoringConfig {
  enabled?: boolean; // 是否启用前端监控
  openId?: string; // 用户标识，用于过滤特定用户
  appkey?: string; // 应用标识
  reportUrl?: string; // 监控数据上报地址
  enableConsoleMonitoring?: boolean; // 是否启用控制台监控
  enableRequestMonitoring?: boolean; // 是否启用网络请求监控
  enableErrorMonitoring?: boolean; // 是否启用错误监控
  customData?: Record<string, any>; // 自定义上报数据
  plugins?: string[] | MonitoringPlugin[]; // 监控插件配置
}

使用示例

H5 环境完整示例

<!DOCTYPE html>
<html>
  <head>
    <title>H5 Debug Example</title>
  </head>
  <body>
    <button id="debug-entry">调试入口</button>

    <script src="./dist/index.umd.js"></script>
    <script>
      const debugTools = EpointM8DebugTools.DebugTools.createH5({
        clickCount: 5,
        entrySelector: "#debug-entry",
        enableWebSocketPlugin: true,
        reportUrl: "https://api.example.com/report",
      });

      // 也可以通过URL参数控制: ?eruda=show
      console.log("Debug tools initialized");
    </script>
  </body>
</html>

小程序环境完整示例

// app.js
import { DebugTools } from "epoint-m8-debug-tools";

App({
  onLaunch() {
    this.debugTools = DebugTools.createMiniProgram({
      clickCount: 6,
      realtimeLogConfig: {
        enabled: true,
        level: "info",
      },
    });
  },
});

// pages/index/index.js
const app = getApp();

Page({
  data: {
    clickCount: 0,
  },

  onTapLogo() {
    // 点击logo触发调试
    app.debugTools.triggerEntryClick();
  },

  onTapShowDebug() {
    // 直接显示调试
    app.debugTools.show();
  },
});

示例文件

项目提供了完整的示例文件供参考：

调试工具示例

examples/test-inline.html - 内联调试工具测试
examples/monitoring-example.html - 前端监控功能演示
examples/miniprogram-monitoring-example.js - 小程序监控使用示例
examples/security-usage-example.ts - 安全功能使用示例
examples/server-security-config.js - 服务器安全配置示例

快速体验

调试工具测试页面 (examples/test-inline.html) 包含：

🔧 H5 环境 eruda 调试面板
📱 小程序调试功能演示
🔌 WebSocket 插件展示
📊 错误上报功能测试

前端监控演示页面 (examples/monitoring-example.html) 包含：

📈 前端监控功能完整演示
🎛️ 监控开关和配置控制
🔐 用户过滤功能测试
📊 控制台、网络、错误监控
🚀 自定义数据上报

小程序监控示例 (examples/miniprogram-monitoring-example.js) 包含：

📱 微信/支付宝小程序监控配置
🎯 不同使用场景示例
🔧 完整的页面集成代码

🎯 监控使用场景

统一监控策略（推荐）

生产和开发环境使用相同的监控配置，通过用户过滤控制监控范围：

// 统一配置 - 生产和开发环境一致
const monitoringConfig = {
  enabled: true,
  enableConsoleMonitoring: true,  // 控制台监控
  enableRequestMonitoring: true,  // 网络请求监控
  enableErrorMonitoring: true,    // 错误监控
  appkey: 'my-app',
  // 通过 openId 控制监控用户
  openId: getCurrentUserOpenId(), // 只监控当前用户
  customData: {
    env: process.env.NODE_ENV || 'development',
    version: '1.0.0'
  }
};

场景示例

开发调试：开启所有监控，实时查看应用状态
生产环境：同样开启完整监控，通过 openId 过滤特定用户
VIP用户监控：只对重要用户启用监控，收集高质量反馈
问题排查：临时为特定用户启用监控，定位问题
性能优化：避免全量监控，只监控需要的用户群体

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

许可证

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

epoint-m8-debug-tools

特性

安装

快速开始

自动检测环境

H5 环境使用

微信小程序环境使用

API 文档

DebugTools

静态方法

实例方法

配置选项

基础配置 (BaseConfig)

H5 环境配置 (H5Config)

小程序环境配置 (MiniProgramConfig)

前端监控配置 (MonitoringConfig)

使用示例

H5 环境完整示例

小程序环境完整示例

示例文件

调试工具示例

快速体验

🎯 监控使用场景

统一监控策略（推荐）

场景示例

开发

许可证