uni-app SDK 接入指引

本文介绍如何在 uni-app 项目中接入 Bugly 专业版。注册产品、接入 SDK 后，验证数据上报成功，即可在 Bugly 专业版的官网使用相关分析功能。

bugly-native 是什么

bugly-native 是我们专门为 uni-app（iOS / Android）移动端提供的 UTS 原生插件，一份 uni-app 工程代码即可同时接入 Bugly 双端 SDK，用于：

崩溃 / 异常自动捕获：Native Crash（C/C++）、Java / Kotlin / Swift / Objective-C 异常自动上报
自定义错误上报：业务侧通过 reportError 主动上报 JS / UTS / 原生自定义错误，附带 tag、user、extraInfo 等扩展信息

接入前准备

在接入 SDK 之前，请务必认真阅读《开发者合规指南》。
SDK 在初始化过程中，可能会采集部分用户信息。请在用户同意《Bugly 专业版 SDK 个人信息保护规则》之后，再进行 SDK 的初始化。SDK 在初始化前，不会收集任何信息。

步骤一：注册产品，获取 AppID 及 AppKey

请参考快速入门，在 Bugly 专业版上创建新产品，创建成功后，在 设置 → 产品信息 中，复制 AppID 及 AppKey。

tip

iOS 与 Android需要使用不同的 AppID 和 AppKey；

步骤二：下载 bugly-native 插件

我们以 UTS 插件包 的形式提供 bugly-native，点击下载：bugly-native.zip。

插件包含：

uni_modules/bugly-native/utssdk/app-ios/ —— iOS 侧，使用cocoapods安装原生SDK
uni_modules/bugly-native/utssdk/app-android/ —— Android 侧，含 bugly.aar
uni_modules/bugly-native/utssdk/interface.uts —— 双端共享的 API 类型定义

下载后，将整个 bugly-native/ 目录放到你的 uni-app 工程根目录下的 uni_modules/ 里，最终目录结构如下：

your-uni-app-project/
├── manifest.json
├── pages.json
├── uni_modules/
│   └── bugly-native/          ← 放在这里
│       ├── package.json
│       ├── readme.md
│       └── utssdk/
│           ├── interface.uts
│           ├── app-ios/
│           │   ├── config.json
│           │   ├── info.plist
│           │   ├── index.uts
│           └── app-android/
│               ├── AndroidManifest.xml
│               ├── config.json
│               ├── index.uts
│               └── libs/bugly.aar
└── ...

步骤三：在业务代码中初始化并使用

在 App.vue 的 onLaunch 或任意合适的入口，调用插件初始化：

import {
  initBugly,
  reportError,
  updateUniqueId,
  updateUserId,
  putUserData,
  BuglyServerHost
} from "@/uni_modules/bugly-native"

// 应用启动时初始化
// initBugly 为位置参数：appId, appKey, debug, channel, logLevel, serverHost
//   - appId     必填，Bugly 控制台的 App ID
//   - appKey    必填，Bugly 控制台的 App Key
//   - debug     是否开启 SDK 内部日志，调试期建议 true，正式发布置为 false
//   - channel   渠道号，可选，无则传 null
//   - logLevel  日志级别 0~4，可选，无则传 null
//   - serverHost 上报域名
initBugly("你的 AppID", "你的 AppKey", true, null, null, BuglyServerHost.BuglyPro)

// 设置设备 ID
updateUniqueId("device_abcdef123456")

// 设置用户 ID
updateUserId("user_123")

// 附加自定义键值对（K/V 均为字符串），会随崩溃一起上报，方便在控制台侧筛查
putUserData("vipLevel", "gold")

// 自定义错误上报
// reportError 为位置参数：message, errorType, errorMsg, jsStack, extraInfo
try {
  // ...业务代码
} catch (e) {
  reportError(
    "业务异常：xxx 流程失败",
    "BizError_Checkout",           // errorType，用于后台聚合
    null,                          // errorMsg，为空时使用 message
    (e as Error).stack || null,    // JS 调用栈
    { step: "checkout" }           // extraInfo：仅本条上报生效的 K/V
  )
}

步骤四：HBuilder 云打包

UTS 插件需要通过 HBuilder 云打包生成包含原生能力的 App。云打包无需本地原生环境，只要工程结构正确、插件放进 uni_modules/，就可以在 HBuilderX 中一键完成 iOS/Android 打包。

1. 在 HBuilderX 中打开 uni-app 工程

确认 uni_modules/bugly-native/ 已放到工程根目录。

2. 使用自定义基座运行调试

菜单 运行 → 运行到手机或模拟器 → 制作自定义调试基座，生成包含 bugly-native 的自定义基座；之后运行时选择 使用自定义基座运行。

danger

UTS 插件不能在标准基座下运行，一定要先制作自定义基座；否则会提示找不到 bugly-native 的原生方法。

3. 云打包发布包

菜单 发行 → 原生 App-云打包：

勾选 Android 或 iOS（可同时勾）
Android 端选择签名证书（正式发版必须用自己的 keystore，不要用公共测试证书）
iOS 端选择开发者证书 + 描述文件
点击打包，等待 DCloud 云端返回 apk / ipa

4. 验证上报

安装打出的包，触发一次崩溃或调用 reportError(...)，几分钟内即可在 Bugly 控制台看到上报数据。

验证接入

安装出包后，可以通过以下方式验证接入是否成功：

主动上报：在业务代码里调用一次 reportError("bugly 接入测试", null, null, null, null)，几分钟内应该能在 Bugly 控制台看到上报
控制台数据：登录 Bugly 专业版控制台，进入你对应产品，查看 崩溃分析 / 异常上报 中的数据

常见问题

HBuilderX 运行提示"找不到 bugly-native 原生方法" → 使用了标准基座，请先制作自定义基座
云打包成功但装机崩溃 / 数据不上报 → 检查 initBugly 的 AppID / AppKey 是否与 Bugly 控制台注册值一致，Android 需检查签名证书对应的 SHA1 是否已在 DCloud 控制台配置

uni-app SDK 接入指引

bugly-native 是什么​

接入前准备​

步骤一：注册产品，获取 AppID 及 AppKey​

步骤二：下载 bugly-native 插件​

步骤三：在业务代码中初始化并使用​

步骤四：HBuilder 云打包​

验证接入​

常见问题​