更新记录

1.0.1（2025-10-30） 下载此版本

处理app兼容

1.0.0（2025-10-29） 下载此版本

1.0

平台兼容性

uni-app(3.6.12)

uni-app x(3.6.12)

wl-debugger

一个功能强大的 uni-app 调试工具，支持控制台日志、网络请求拦截、本地存储管理和 WebSocket 数据监控等功能。

功能特性

• 📝 控制台日志 - 捕获并显示 console.log、console.error、console.info、console.warn
• 🌐 网络请求拦截 - 监控和调试 uni.request 请求
• 💾 本地存储管理 - 查看和管理本地存储数据
• 🔌 WebSocket 监控 - 实时监控 WebSocket 连接和数据

前置要求

wl-debugger 需要在 uni-app 项目中使用 @uni-ku/root 插件来实现全局组件的注册和显示。

为什么需要 @uni-ku/root？

在 uni-app 中，App.vue 不能直接渲染模板内容，要实现全局组件在所有页面显示，需要使用 @uni-ku/root 提供的全局布局功能。@uni-ku/root 通过 App.ku.vue 文件提供了一个类似 RouterView 的全局布局容器，可以放置需要全局显示的组件。

安装步骤

1. 安装 @uni-ku/root 插件

使用 npm 或 pnpm 安装：

# 使用 npm
npm install @uni-ku/root --save-dev

# 使用 pnpm
pnpm add @uni-ku/root --save-dev

2. 配置 vite.config.js

在项目根目录创建或修改 vite.config.js（或 vite.config.ts），添加 @uni-ku/root 插件：

// vite.config.js
import Uni from '@dcloudio/vite-plugin-uni'
import UniKuRoot from '@uni-ku/root'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // 若存在改变 pages.json 的插件，请将 UniKuRoot 放置其后
    UniKuRoot(),
    Uni()
  ]
})

3. 安装 Vue（如果尚未安装）

确保项目中已安装 Vue 3：

npm install vue
# 或
pnpm add vue

4. 安装 wl-debugger

如果 wl-debugger 已存在于 uni_modules 目录中，则无需额外安装。如果通过其他方式引入，请确保组件路径正确。

使用方法

1. 初始化 Debugger

在 main.js 中初始化 Debugger：

// main.js
import App from './App'
import { createSSRApp } from 'vue'
import { Debugger } from '@/uni_modules/wl-debugger/components/wl-debugger/common/debugger'

export function createApp() {
  const app = createSSRApp(App)
  // 初始化 Debugger
  Debugger.getInstance()
  return {
    app
  }
}

2. 创建 App.ku.vue 文件

在项目根目录创建 App.ku.vue 文件（与 App.vue 同级）：

<script setup lang="ts">
import WlDebugger from '@/uni_modules/wl-debugger/components/wl-debugger/index.vue'
</script>

<template>
  <KuRootView />
  <!-- 全局调试器组件，会在所有页面上层显示 -->
  <WlDebugger />
</template>

说明：

• <KuRootView /> 是 @uni-ku/root 提供的路由视图组件，所有页面内容会渲染在这里
• <WlDebugger /> 是调试器组件，会在所有页面上层显示，不会遮挡页面内容

3. 开始使用

完成上述配置后，运行项目，调试器会自动出现在所有页面上。点击调试器按钮即可打开调试面板。

功能模块

Console（控制台）

自动捕获页面的 console 输出：

• console.log()
• console.error()
• console.info()
• console.warn()

所有日志会实时显示在调试器的 Console 标签页中。

InterceptorRequest（请求拦截）

自动拦截并显示：

• uni.request 请求
• 请求 URL、方法、参数
• 响应数据和状态码
• 请求耗时

可以在调试器中查看所有网络请求的详细信息。

StorageInit（存储管理）

显示并管理本地存储数据：

• localStorage
• sessionStorage
• uni.setStorage 存储的数据

可以查看、编辑和删除存储项。

WebSocketData（WebSocket 监控）

实时监控 WebSocket 连接：

• 连接状态
• 发送和接收的消息
• 连接事件

自定义配置

自定义插件

如果需要自定义插件或修改默认插件：

// main.js
import { Debugger } from '@/uni_modules/wl-debugger/components/wl-debugger/common/debugger'
import { ConsoleInit, InterceptorRequestPlugin } from '@/uni_modules/wl-debugger/components/wl-debugger/common/plugIn'

export function createApp() {
  const app = createSSRApp(App)

  // 使用自定义插件列表
  Debugger.getInstance({
    plugins: [
      ConsoleInit,
      InterceptorRequestPlugin,
      // 添加其他插件...
    ]
  })

  return {
    app
  }
}

动态加载插件

import { Debugger } from '@/uni_modules/wl-debugger/components/wl-debugger/common/debugger'
import { YourCustomPlugin } from './your-custom-plugin'

// 动态加载插件
const debugger = Debugger.getInstance()
debugger.loadPlugin(YourCustomPlugin)

移除插件

const debugger = Debugger.getInstance()
debugger.removePlugin('Console')

API 参考

Debugger 类

静态方法

• Debugger.getInstance(options?) - 获取 Debugger 单例实例
• Debugger.resetInstance() - 重置单例实例

实例方法

• loadPlugin(Plugin) - 动态加载插件
• getPlugin(pluginName) - 获取指定插件
• removePlugin(pluginName) - 移除指定插件

PluginBase 接口

自定义插件需要实现以下接口：

interface PluginBase {
  NAME: string              // 插件名称
  DATA: any                 // 插件数据类实例
  componentsName: string    // 插件组件名称
  init?: () => void         // 初始化插件
  eliminateAll?: () => void // 清除所有数据
  getData?: () => any       // 获取插件数据（返回 Promise 或同步数据）
}

注意事项

1. 全局组件位置：确保在 App.ku.vue 中正确引入 WlDebugger 组件
2. Vue 版本：需要 Vue 3.x 版本
3. uni-app 版本：建议使用 uni-app 3.1.0 及以上版本
4. 开发环境：建议仅在开发环境使用，生产环境可通过条件编译移除

常见问题

Q: 调试器没有显示？

A: 检查以下几点：

1. 是否安装了 @uni-ku/root 插件
2. 是否正确配置了 vite.config.js
3. 是否创建了 App.ku.vue 文件
4. 是否在 main.js 中初始化了 Debugger

Q: 如何只在开发环境显示调试器？

A: 使用条件编译：

<!-- App.ku.vue -->
<template>
  <KuRootView />
  <!-- #ifdef H5 -->
  <!-- 开发环境显示 -->
  <WlDebugger />
  <!-- #endif -->
</template>

Q: 可以自定义调试器的样式吗？

A: 可以，直接修改 WlDebugger 组件内部的样式，或通过传入样式属性自定义。

许可证

MIT

更新日志

查看 changelog.md 了解版本更新记录。