跳到主要内容

Uni-app Vite 插件使用指南

听云 uni-app Vue3 操作采集编译插件，配合听云 App SDK 或小程序 SDK，为页面和组件模板中的用户操作提供名称信息。

适用范围​

适用于使用 Vite 编译的 uni-app Vue3 项目：

  • App：Vue/nvue 模板，目标为 app 或 app-harmony。
  • 小程序：微信、百度、支付宝、钉钉、京东、飞书。

插件处理模板中显式绑定的 click、tap 事件，默认启用 click；tap 需通过 action.events 开启。

  • App Vue：支持框架识别的内置组件节点，例如 view、text、button。
  • App nvue：支持 view、text、image、button 等节点；部分内置组件（例如 picker、checkbox、slider）暂不插桩。鸿蒙 .nvue 走 Vue 编译分支时按 App Vue 范围处理。
  • 普通自定义组件标签上的事件不插桩，组件内部模板中符合上述条件的节点可以插桩。

组件还需在目标平台支持并实际触发对应事件；插件不会新增业务监听器，也不处理 change、input 等其他事件。Vue2、uni-app x 和普通 Vue/Vite 项目不在处理范围内。

安装向导​

1. 安装插件​

在项目根目录执行：

npm install --save-dev @tingyun-common/vite-plugin-uniapp

2. 配置插件​

按项目创建方式选择下面的接入步骤。CLI 项目即使在 HBuilderX 中打开，仍按 CLI 项目处理。

HBuilderX 创建的项目：没有 Vite 配置​

在 manifest.json 同级新建 vite.config.js 或 vite.config.ts，二选一即可。以下以 vite.config.js 为例：

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

export default defineConfig({
  plugins: [
    uni(),
    createTingyunUniAppPlugin(),
  ],
})

项目位置如下：

项目根目录/
├── manifest.json
├── pages.json
├── main.js
├── package.json
└── vite.config.js

保留示例中的 uni()，它负责 uni-app 项目的编译。Vite 和 uni-app 编译依赖由 HBuilderX 提供，无需额外安装。

保存配置后，在 HBuilderX 中重新运行项目即可。Vite 配置说明见 DCloud 文档。

HBuilderX 创建的项目：已有 Vite 配置​

打开与 manifest.json 同级的 vite.config.js 或 vite.config.ts，添加下面标有 + 的两行，其他配置保持原样（+ 仅用于标记新增内容，无需复制）：

 import { defineConfig } from 'vite'
 import uni from '@dcloudio/vite-plugin-uni'
+import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

 export default defineConfig({
   plugins: [
     uni(),
+    createTingyunUniAppPlugin(),
     // ...其他已有插件
   ],
 })

保存后，在 HBuilderX 中重新运行项目。

CLI 创建的项目​

打开与 package.json 同级的 vite.config.js 或 vite.config.ts，添加下面标有 + 的两行，其他配置保持原样（+ 仅用于标记新增内容，无需复制）：

 import { defineConfig } from 'vite'
 import uni from '@dcloudio/vite-plugin-uni'
+import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

 export default defineConfig({
   plugins: [
     uni(),
+    createTingyunUniAppPlugin(),
     // ...其他已有插件
   ],
 })

保存后，执行项目原有的 npm 运行或构建命令。

3. 接入目标平台 SDK​

编译插件在构建时补充用户操作的采集信息，实际采集和上报由运行时 SDK 完成。请按目标平台接入对应的 SDK：

  • App：接入 @tingyun-sdk/uniapp-app，详见该 SDK 的 README。
  • 小程序：接入所选平台的听云小程序 SDK，详见该 SDK 的 uni-app 接入文档。

4. 验证接入​

  1. 重新编译，在 HBuilderX 编译控制台或 CLI 终端查看 [tingyun-uniapp-plugin] 的 [build_end] 日志。result=completed 且 counts 中的 injected 大于 0，表示已完成操作插桩。
  2. 运行项目，点击页面中已有的 @click 按钮，等待上报后在听云 Web 控制台查看对应操作。名称规则见下方事件与操作名称。

配置说明​

以下类型展示可用配置和默认值。业务项目从包中导入 TingyunUniAppPluginOptions 即可使用类型提示。

type MiniProgramPlatform =
  | 'mp-weixin' | 'mp-baidu' | 'mp-alipay'
  | 'mp-dingtalk' | 'mp-jd' | 'mp-lark'

type LogLevel = 'error' | 'warn' | 'info' | 'debug'

interface TingyunUniAppPluginOptions {
  action?: {
    enabled?: boolean // 默认 true
    events?: readonly ('click' | 'tap')[] // 默认 ['click']，至少一项
    exclude?: readonly string[] // 默认 []，相对于源码根的 glob
    miniProgram?: {
      enabled?: boolean // 默认 true
      platforms?: readonly MiniProgramPlatform[] // 默认全部六端，至少一项
    }
    app?: {
      enabled?: boolean // 默认 true
      renderers?: readonly ('vue' | 'nvue')[] // 默认两者，至少一项
    }
  }
  failureMode?: 'continue' | 'throw' // 默认 continue，控制节点处理失败
  logging?: {
    console?: {
      enabled?: boolean // 默认 true
      level?: LogLevel // 默认 info
    }
    file?: {
      enabled?: boolean // 默认 false
      level?: LogLevel // 默认 debug
      directory?: string // 默认 .tingyun/logs，相对项目根或绝对路径
      maxFileSize?: number // 默认 5242880 字节，至少 65536
      maxBuilds?: number // 默认 10，保留的非活动构建轮数
    }
  }
}

JavaScript 项目直接传配置对象即可。TypeScript 项目示例：

import {
  createTingyunUniAppPlugin,
  type TingyunUniAppPluginOptions,
} from '@tingyun-common/vite-plugin-uniapp'

const options: TingyunUniAppPluginOptions = {
  action: {
    events: ['click', 'tap'],
    exclude: ['pages/legacy/**'],
  },
  logging: {
    file: { enabled: true },
  },
}

// 在现有 plugins 数组中使用 createTingyunUniAppPlugin(options)

action.enabled 控制编译插件的操作处理；App、小程序子开关用于选择平台。app.renderers 按模板编译阶段区分，nvue 阶段引用的 .vue 子组件也受 nvue 配置控制。

failureMode: 'continue' 在当前节点处理失败后继续构建，'throw' 将该异常交给构建工具。配置和插件安装失败会输出诊断并停止本插件处理；宿主自身的编译错误仍由宿主报告。

事件与操作名称​

通过 action.events 选择需要采集的模板事件，默认采集 @click；设置为 ['click', 'tap'] 时，也会采集 @tap。

同一节点同时绑定这两种事件且均已启用时，App 分别处理；小程序优先使用 click 的操作名称。实际业务事件触发次数由平台决定。

操作名称根据模板写法确定：

模板写法操作名称
@click="save"save
@click="form.save(item)"form.save
静态 data-ty-action="购买商品"购买商品
页面匿名表达式例如 pages/home/index.vue#f0
组件匿名表达式例如 components/BuyButton.vue#f0

模板路径相对于源码根，保留 .vue 或 .nvue。编号按启用事件的源码顺序分配；同一组件复用于不同页面时名称相同。路径不可用或超过 128 字符时使用 #fN 并输出诊断。

App SDK 与小程序 SDK 的操作名称长度上限为 1024，超长截断后继续采集，相同前缀可能产生同名名称。

推荐通过静态属性指定名称：

<button data-ty-action="提交订单" @click="submit">提交</button>

App 对动态 :data-ty-action 绑定跳过该节点的操作处理；小程序由运行时 SDK 读取 dataset。

文件与节点排除​

文件排除相对于源码根：CLI 通常是 src/，HBuilderX 创建的项目通常是根目录。使用 / 分隔和相对路径，例如 pages/legacy/**、components/DebugButton.vue。

规则区分大小写，支持 *、**、?、字符类、大括号和 extglob；目录写成 dir/**。规则使用相对路径，不接受反斜杠、独立的 ./.. 路径段或前导 !。排除一个页面只作用于该文件，其引用的组件按各自路径判断。

节点使用静态标记：

<view data-ty-action-ignore="true" @click="parentClick">
  <button @click="childClick">子节点仍参与采集</button>
</view>

标记只作用于当前节点，值须为字符串 "true"。小程序已有的 data-ty-action 属性仍保留，运行时 SDK 可继续按该属性采集。

兼容性​

已在 uni-app CLI 编译器 4.75 和 HBuilderX 5.24 环境完成构建验证。CLI 项目的 Node.js 环境要求见 uni-app 官方文档。

验证与排查​

接入验证见安装向导。未采集到操作时，检查平台、事件和渲染类型是否启用，以及目标平台 SDK 是否完成初始化并开启操作采集。

需要查看具体模板处理过程时设置 logging.console.level: 'debug'。常见诊断：

诊断检查方向
installed插件已安装到编译链，继续检查运行时 SDK
host_unsupported确认项目为 uni-app Vue3/Vite
vue_entry_unavailable / compiler_unavailable检查 uni()、编译器版本及重复 Vue 插件
config_invalid按提示字段核对配置类型和值
duplicate_plugin同一构建只保留一次注册，第一次配置生效
init_failed / node_failed根据阶段、文件及位置定位失败
template_path核对模板路径，必要时设置静态名称

保存构建日志​

createTingyunUniAppPlugin({
  logging: {
    console: { level: 'info' },
    file: { enabled: true, level: 'debug' },
  },
})

控制台默认输出基本构建摘要，debug 增加模板处理细节。日志格式为 YYYY-MM-DD HH:mm:ss.SSS ±HH:MM [tingyun-uniapp-plugin] [LEVEL] [code] message，包含本地时间及 UTC 偏移，级别大写、诊断码小写。文件默认保存在 .tingyun/logs，开始摘要给出 buildId 和实际路径；建议将目录加入 .gitignore。

每轮构建生成独立日志，超过 maxFileSize 后分片；maxBuilds 按非活动构建轮次清理。watch 重建单独记录，App 的 Vue/nvue 构建分别记录。插件结束摘要标记该编译阶段结束，最终构建结果以 uni-app 输出为准。