@mysgame/h5-debug-kit

H5 移动端调试面板，支持 Eruda 和 vConsole。

提供四合一调试面板，内部 Tab 切换：

| Tab | 功能 | |-----|------| | Token | 读取 APP 内 localStorage Token，一键发飞书卡片，点击「同步至本地」自动写入开发机 | | 日志 | 实时展示控制台日志，按级别筛选，勾选条目推送飞书 | | 存储 | 可视化 localStorage 所有键值，勾选推送飞书 | | 设置 | Webhook URL 和来源标识，持久化到本地 |

安装

pnpm add @mysgame/h5-debug-kit
# 或
npm install @mysgame/h5-debug-kit

Eruda / vConsole 作为 peer dependency，按需安装：

pnpm add eruda        # 使用 Eruda
pnpm add vconsole     # 使用 vConsole

快速接入

Eruda

推荐从子路径引入，bundle 更干净：

import eruda from 'eruda'
import { initDevTool } from '@mysgame/h5-debug-kit/eruda'

eruda.init()

initDevTool(eruda, {
  webhookUrl: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  storageKey: 'myAppToken',   // localStorage 中存 Token 的 key
  source: '我的 APP',         // 显示在飞书卡片中，不填自动从 UA 检测
})

vConsole

第一个参数传 VConsole.VConsolePlugin（构造函数），而不是整个 VConsole 类：

import VConsole from 'vconsole'
import { initVConsoleDevTool } from '@mysgame/h5-debug-kit/vconsole'

const vc = new VConsole()

initVConsoleDevTool(VConsole.VConsolePlugin, vc, {
  webhookUrl: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx',
  storageKey: 'myAppToken',
  source: '我的 APP',
})

仅在非生产环境加载（推荐）

if (import.meta.env.DEV) {
  import('eruda').then(({ default: eruda }) => {
    eruda.init()
    import('@mysgame/h5-debug-kit/eruda').then(({ initDevTool }) => {
      initDevTool(eruda, {
        webhookUrl: import.meta.env.VITE_FEISHU_WEBHOOK,
        storageKey: 'myAppToken',
      })
    })
  })
}

vConsole 版本：

if (import.meta.env.DEV) {
  import('vconsole').then(({ default: VConsole }) => {
    const vc = new VConsole()
    import('@mysgame/h5-debug-kit/vconsole').then(({ initVConsoleDevTool }) => {
      initVConsoleDevTool(VConsole.VConsolePlugin, vc, {
        webhookUrl: import.meta.env.VITE_FEISHU_WEBHOOK,
        storageKey: 'myAppToken',
      })
    })
  })
}

导入路径说明

| 路径 | 内容 | 适用场景 | |------|------|----------| | @mysgame/h5-debug-kit | 全量导出（Eruda + vConsole） | 兼容旧代码 | | @mysgame/h5-debug-kit/eruda | 仅 Eruda 接入 | 只用 Eruda | | @mysgame/h5-debug-kit/vconsole | 仅 vConsole 接入 | 只用 vConsole | | @mysgame/h5-debug-kit/vite-plugin | Vite 插件 | Token 回调路由 |

Token 同步工作流

手机 APP 打开 H5
  → 打开 Eruda/vConsole 面板，切到 Token Tab
  → 点击「发送 Token 卡片」
  → 飞书机器人收到卡片，卡片上有「同步至本地」按钮
  → 开发者手机点击「同步至本地」
  → 浏览器打开当前调试页面（带 __sync_token__ 参数）
  → 页面自动把 Token 写入 localStorage，URL 参数自动清除
  → 本地开发机接口调试畅通

纯前端方案：Token 同步不依赖 Vite dev server，本地和测试环境同样可用，无需额外配置。

飞书机器人配置

1. 飞书群 → 群设置 → 机器人 → 添加机器人 → 自定义机器人
2. 复制 Webhook 地址，填入 webhookUrl
3. 安全设置：关闭「关键词」校验，否则日志内容可能触发拦截

API

initDevTool(eruda, options)

从 @mysgame/h5-debug-kit/eruda 引入。

initVConsoleDevTool(VConsolePlugin, vc, options)

从 @mysgame/h5-debug-kit/vconsole 引入。注意第一个参数是 VConsole.VConsolePlugin（构造函数），不是 VConsole 类本身。

options 参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | webhookUrl | string | — | 飞书机器人 Webhook 地址（必填） | | storageKey | string | 'token' | localStorage 中存 Token 的 key | | source | string | UA 自动检测 | 飞书卡片中显示的来源标识 | | parseToken | (raw: string) => ParsedToken | 内置 JSON 解析 | 自定义 Token 解析逻辑 | | panelName | string | 'DevTool' | 面板标签名 | | logMaxLines | number | 100 | 日志最大缓存条数 | | extraTabs | DevToolTab[] | [] | 自定义扩展 Tab |

自定义 Token 解析

默认会尝试把 localStorage 值 JSON 解析，提取 token / access_token / accessToken 字段。格式不同时自定义：

import { initDevTool } from '@mysgame/h5-debug-kit/eruda'

initDevTool(eruda, {
  webhookUrl: '...',
  storageKey: 'session',
  parseToken: (raw) => {
    const obj = JSON.parse(raw)
    return {
      token: obj.data.accessToken,
      extraTokens: { refreshToken: obj.data.refreshToken },
    }
  },
})

扩展自定义 Tab

import { initDevTool, type DevToolTab } from '@mysgame/h5-debug-kit/eruda'

const gameStateTab: DevToolTab = {
  id: 'game-state',
  label: '游戏',
  render(ctx) {
    return `<div style="padding:8px;color:#e2e8f0;">
      <div>当前关卡：<span id="my-level">-</span></div>
    </div>`
  },
  onMount(panel, ctx) {
    // 绑定事件
  },
  onActivate(panel, ctx) {
    // 切换到这个 Tab 时刷新内容
    ;(panel.querySelector('#my-level') as HTMLElement).textContent = String((window as any).__gameLevel ?? '-')
  },
}

initDevTool(eruda, {
  webhookUrl: '...',
  extraTabs: [gameStateTab],
})

兼容旧版

• initTokenPanel 是 initDevTool 的别名，旧代码无需修改
• 从 @mysgame/h5-debug-kit 根路径引入仍然有效，但推荐迁移到子路径

0.3.x → 0.4.x 迁移说明：

// 旧写法
import { initVConsoleDevTool } from '@mysgame/h5-debug-kit'
initVConsoleDevTool(VConsole, vc, options)

// 新写法（0.4.x）
import { initVConsoleDevTool } from '@mysgame/h5-debug-kit/vconsole'
initVConsoleDevTool(VConsole.VConsolePlugin, vc, options)

License

MIT