uniapp-native-dev-tools

UniApp + Vue3 运行时调试面板，支持 Android / iOS / HarmonyOS 三端。

在原生 App 打包后无法使用 Chrome DevTools 的环境下，提供类似浏览器控制台的调试能力：网络请求记录、日志查看、本地存储浏览、设备信息展示。

截图

┌─────────────────────────────────┐
│ DevTools                    [×] │
├─────────────────────────────────┤
│ Console │ Network │ Storage │ 设备│
├─────────────────────────────────┤
│ [ALL] [LOG] [WARN] [ERROR]      │
│ [搜索框]                          │
│ ▸ [WARN] 10:23:01  message      │
│ ▸ [ERR]  10:23:05  error detail │
└─────────────────────────────────┘

功能

| Tab | 功能 | |-----|------| | Console | 拦截 console.log/warn/error/info/debug，支持级别过滤、关键词搜索、点击展开完整内容、长按复制 | | Network | 拦截 uni.request，记录 URL、方法、请求参数、响应体、状态码、耗时，展开显示完整 URL 和 JSON | | Storage | 枚举 uni.getStorageSync 所有 key/value，支持搜索、点击展开值、长按复制 | | 设备 | 展示 uni.getSystemInfoSync 的平台、设备、屏幕、App 版本信息 |

安装

本地引用：

# 在宿主项目 package.json 中添加
"uniapp-native-dev-tools": "file:../uniapp-native-dev-tools"

npm install

npm 发布后：

npm install uniapp-native-dev-tools

本包以源码形式分发（.vue 文件不预编译），需由宿主项目的 @dcloudio/vite-plugin-uni 统一编译。

使用

1. 注册插件

// src/main.js
import { createDevTools } from 'uniapp-native-dev-tools'

export default function createApp() {
  const app = createSSRApp(App)
  // enabled 由宿主决定，通常在非生产环境开启
  app.use(createDevTools({ enabled: !isEnvPro() }))
  // ...
}

2. 挂载面板组件

将 DevToolsPanel 放在全局 layout 中，确保每个页面都能显示悬浮球和面板。

<!-- src/layouts/default.vue -->
<template>
  <slot />
  <DevToolsPanel v-if="isPageOnTop" />
</template>

<script setup>
import { ref } from 'vue'
import { onShow, onHide } from '@dcloudio/uni-app'
import { DevToolsPanel } from 'uniapp-native-dev-tools'

// v-if 配合 onShow/onHide 确保页面栈中只有当前页渲染面板，避免多实例
const isPageOnTop = ref(true)
onShow(() => { isPageOnTop.value = true })
onHide(() => { isPageOnTop.value = false })
</script>

依赖 @uni-helper/vite-plugin-uni-layouts 布局插件，在 vite.config.js 中启用 UniLayouts() 并配置 uni.layouts.config.ts。

3. 配置触发入口

面板本身不提供触发按钮，由宿主项目决定在何处打开。推荐用 useTapTrigger 在隐蔽位置连续点击触发：

<!-- 示例：在"关于"或"个人中心"页某个空白区域 -->
<view @tap="onDevTrigger" style="width: 60px; height: 60px;" />

<script setup>
import { useTapTrigger, openDevTools } from 'uniapp-native-dev-tools'

// 3 秒内点击 5 次触发
const onDevTrigger = useTapTrigger(5, 3000, openDevTools)
</script>

API

createDevTools(options)

创建 Vue plugin，传入 app.use()。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否安装拦截器；false 时插件为空操作 | | maxConsoleLogs | number | 300 | Console 日志环形缓冲上限 | | maxNetworkLogs | number | 200 | Network 请求记录环形缓冲上限 |

DevToolsPanel

悬浮面板组件，放在 layout 的 <slot /> 后。状态由内部 panelState 控制，组件挂载但 panelState === 'hidden' 时不渲染任何内容。

openDevTools()

打开面板，状态机转换：

hidden → ball（显示悬浮球）
ball   → panel（展开完整面板）
panel  → 无变化

closeDevTools()

将面板缩回悬浮球（panel → ball）。

hideDevTools()

完全隐藏，包括悬浮球（任意状态 → hidden）。

useTapTrigger(count, ms, onTrigger)

返回一个事件处理函数，在 ms 毫秒内连续触发 count 次后调用 onTrigger。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | count | number | 5 | 触发所需点击次数 | | ms | number | 3000 | 计数窗口（毫秒），超时后重置 | | onTrigger | function | — | 达到次数时的回调 |

destroyDevTools()

卸载所有拦截器，还原 console.* 和 uni.request（一般无需主动调用）。

注意事项

• 生产环境：通过 enabled: false 禁用后，插件不安装任何拦截器，DevToolsPanel 挂载但不渲染内容，无运行时副作用。
• console 拦截：若宿主项目在非 dev 构建中使用 Terser drop_console: true，源码中的 console.* 调用会在编译期被移除，拦截器只能捕获运行时动态产生的日志。网络拦截不受影响。
• 多页面实例：UniApp 原生端页面栈会保留多个页面实例，务必在 layout 中配合 onShow/onHide 使用 v-if 控制 DevToolsPanel 的挂载，避免出现多个悬浮球。
• HarmonyOS：uni.getStorageInfoSync() 在部分鸿蒙版本可能不支持 key 枚举，Storage Tab 会提示降级。

文件结构

uniapp-native-dev-tools/
├── index.js                        # 公共 API 入口
├── package.json
├── README.md
└── src/
    ├── logStore.js                 # 响应式日志/网络记录存储
    ├── consoleInterceptor.js       # console.* 拦截器
    ├── networkInterceptor.js       # uni.request 拦截器
    └── components/
        ├── DevToolsPanel.vue       # 主悬浮面板
        └── tabs/
            ├── ConsoleTab.vue
            ├── NetworkTab.vue
            ├── StorageTab.vue
            └── SystemTab.vue

依赖

| 依赖 | 版本要求 | 说明 | |------|----------|------| | vue | ^3.0.0 | peerDependency | | @dcloudio/uni-app | * | peerDependency，提供 uni 全局对象及页面生命周期 |

License

MIT

作者

kanhing ([email protected])