1. 为什么移动端项目需要一套崩溃采集方案做过移动端项目的人都有一个共识线上崩溃是最让人头疼的问题没有之一。尤其是Unity打包出来的Android应用一旦发到用户手里崩溃日志的获取难度比原生Android开发要高出一个量级。原因很简单Unity的C#层和Android的Java层是两套运行时C#侧的异常如果没被捕获往往直接导致进程挂掉而Java侧的原生崩溃同样会让整个应用闪退。你面对的可能是空指针、可能是内存溢出、可能是某个第三方SDK在特定机型上的兼容性问题但用户只会告诉你一句话“打开就闪退了。”这就是崩溃采集SDK存在的意义。它要解决的核心问题有三个第一自动捕获未处理的异常和信号包括C#层的托管异常和Java层的原生崩溃第二把堆栈信息、设备信息、系统版本、内存状态等上下文一并上报到服务端第三在控制台里把海量崩溃聚合归类让你能按版本、按机型、按发生频率去定位最该优先修的那几个问题。Bugly就是这类方案里在国内Unity圈子里用得比较多的一款。它本身是面向移动端的崩溃监控与运营统计平台提供了Android、iOS、Unity等多个接入方式。对于Unity项目来说接入Android端之后你既能拿到C#脚本抛出的异常堆栈也能拿到Java层的崩溃记录还能顺带看到ANR、卡顿之类的性能数据。这篇文章就围绕Unity项目接入Bugly Android端这件事把整个流程、原理、踩坑点和实操细节完整拆一遍。适合谁看如果你正在做一个Unity移动端项目准备上线或者已经上线但苦于没有崩溃监控手段那这篇内容基本可以照着抄作业。如果你只是听说过Bugly但没实际接过也可以把它当成一份带经验注释的接入手册。我会尽量把每一步为什么这么做讲清楚而不是只丢一堆步骤让你自己猜。2. 接入前的整体设计与方案选型2.1 为什么Unity接Android端SDK不是简单加个依赖很多从纯Android转过来的人会觉得接个SDK不就是加个依赖、初始化一下的事吗在Unity项目里还真不是。Unity的Android打包机制决定了你的最终产物是一个APK但这个APK里包含了Unity引擎的so库、C#编译出来的il2cpp或mono运行时、以及一个由Unity生成的Android工程壳。你要接入的Bugly Android SDK本质上是一个Java层的aar库它需要被合并进这个壳工程里同时还要和Unity的C#层建立通信。这就带来几个关键问题aar怎么放进Unity工程、AndroidManifest怎么合并、初始化代码在哪里调用、C#层怎么主动上报自定义日志。每一个环节都有坑而且不同Unity版本、不同Gradle版本下表现还不一样。所以接入之前先把整体思路理清楚比上来就复制粘贴配置要重要得多。整体方案上我采用的是“Unity导出Android工程 手动集成SDK”的路线而不是依赖某些第三方封装的Unity插件。原因有几个一是插件往往滞后于SDK版本遇到问题不好排查二是手动集成能让你完全掌控AndroidManifest和Gradle配置出问题知道去哪找三是Bugly本身的Android接入文档已经比较清晰手动做一遍并不复杂。当然如果你的项目已经用了某个成熟的Unity崩溃采集插件也可以参考本文的思路去理解底层发生了什么。2.2 崩溃采集的核心原理信号捕获与异常钩子在讲具体步骤之前有必要先搞明白Bugly在Android端到底是怎么捕获崩溃的。这决定了你后面排查问题时能不能看懂日志。Android端的崩溃大致分两类。一类是Java/Kotlin层的未捕获异常这类异常会走到Thread.UncaughtExceptionHandlerBugly通过替换默认的处理器在异常抛出时记录堆栈并上报。另一类是Native层的崩溃比如C代码里的段错误、Unity引擎本身的崩溃这类不会走Java异常机制而是通过信号处理器signal handler来捕获比如SIGSEGV、SIGABRT这些。Bugly的native库会注册这些信号的处理函数在进程崩溃前把关键信息dump下来。而Unity的C#层异常情况更特殊一些。il2cpp模式下C#代码被编译成C异常处理机制和纯C#运行时不同。Bugly的Unity方案通常是通过在C#层做一层包装捕获Application.logMessageReceived回调里的异常日志再通过JNI调用把信息传给Java层上报。所以你在控制台看到的C#异常堆栈其实是经过这一层转发上来的。理解了这一点你就能明白为什么有时候C#的异常在控制台里堆栈不全或者某些native崩溃没有C#堆栈——因为它们走的是完全不同的捕获路径。2.3 版本选择与依赖关系梳理Bugly的Android SDK版本更新比较频繁Unity这边对应的接入方式也随着Unity版本变化。我的建议是优先选择官方文档里标注为稳定版的SDK版本不要盲目追最新。因为最新版可能刚修完某个bug但引入了新的兼容性问题而你的项目未必需要那些新特性。依赖关系上Bugly Android SDK主要依赖以下几个方面一是Android SDK的最低版本要求通常要求minSdkVersion在16以上现在一般项目都是21起步问题不大二是需要网络权限和存储权限用于上报和缓存日志三是如果要用到native崩溃捕获需要确保对应的so库被正确打包进APK。这些在后面的配置环节都会具体展开。另外要提醒一点Bugly的统计和崩溃上报是两套能力如果你只关心崩溃可以只开崩溃模块减少不必要的初始化开销。这个在初始化配置里可以控制。3. 核心细节解析与实操要点3.1 获取App ID与初始化时机的选择接入的第一步是在Bugly控制台创建应用拿到对应的App ID。这个ID是上报数据的唯一标识每个应用一个不要混用。创建的时候注意选择平台为Android因为Unity项目最终是以Android应用的形式存在的。拿到App ID之后关键问题是初始化代码写在哪里很多教程会告诉你写在MainActivity的onCreate里但对于Unity项目来说MainActivity往往是Unity自动生成的你直接改它会在下次导出时被覆盖。正确的做法是创建一个自定义的Activity继承自UnityPlayerActivity然后在里面做初始化再在AndroidManifest里把启动Activity指向你自己的这个类。初始化时机也有讲究。Bugly的初始化要尽早最好在Application的onCreate或者自定义Activity的onCreate最前面调用这样才能捕获到尽可能早的崩溃。如果你放在很后面才初始化那初始化之前发生的崩溃就采集不到了。但也不能太早到影响启动速度所以一般放在Activity的onCreate里、super.onCreate之后立刻执行是个比较平衡的选择。注意初始化时传入的App ID必须是Android平台对应的那个如果你在控制台建了多个平台的应用别拿错ID否则数据会上报到错误的应用下。3.2 AndroidManifest合并的坑与权限配置Unity导出Android工程后AndroidManifest.xml里已经有一堆Unity自己需要的配置。你手动加Bugly相关配置时最容易出问题的地方就是权限和组件声明。Bugly需要的基础权限包括网络访问、网络状态读取、以及写入外部存储用于缓存日志。这些权限在Android 6.0以上需要动态申请但Bugly内部一般会自己处理你只需要在Manifest里声明即可。不过要注意如果你的项目targetSdkVersion比较高某些权限的声明方式可能有变化比如存储权限在Android 10以上分成了分区存储Bugly较新的版本已经适配老版本可能会有问题。组件声明方面Bugly会注册一些ContentProvider和Service用于初始化和上报。这些在aar里已经声明好了通过Manifest合并会自动带进来。但如果你在build.gradle里配置了tools:noderemove之类的规则可能会误删掉Bugly的组件导致初始化失败。这个坑我在一个项目里踩过排查了半天才发现是合并规则的问题。3.3 C#层日志上报的桥接设计Bugly Android SDK本身是Java接口Unity的C#层要调用它必须通过JNI。这里有两种做法一种是直接用AndroidJavaClass和AndroidJavaObject在C#里反射调用Java方法另一种是写一个Java桥接类暴露简单的静态方法给C#调用。我推荐第二种原因是反射调用写起来啰嗦而且容易因为方法签名不匹配而出错。写一个桥接类把需要暴露给C#的方法比如上报自定义日志、设置用户标识、上报异常都封装成静态方法C#侧只需要调用这个桥接类即可。这样职责清晰后续SDK升级时也只需要改桥接类。桥接类里要注意线程问题。Bugly的上报接口一般可以在任意线程调用但如果你在C#侧的子线程里调用JNI要确保JNI环境正确附加。Unity的AndroidJavaObject在子线程使用时需要先AttachCurrentThread否则会报JNI错误。这个细节很多教程不会提但实际项目中一旦用到多线程上报就会遇到。3.4 符号表与堆栈还原的必要性这一块是很多人容易忽略但极其重要的部分。Unity打包出来的C#代码在il2cpp模式下会被编译成C再编译成机器码崩溃时拿到的堆栈是机器码地址没有符号表的话你根本看不懂对应的是哪个C#方法。所以你需要在上传APK的同时把对应的符号表文件也上传到Bugly这样控制台才能把机器码地址还原成可读的函数名和行号。符号表的生成和上传有专门的工具一般在Unity打包完成后在导出的Android工程目录里能找到对应的符号文件。上传时要注意版本号对应每个发布的版本都要上传对应的符号表否则那个版本的崩溃堆栈就无法还原。我见过有团队发了十几个版本但只传了一次符号表结果后面所有版本的崩溃堆栈都是乱码等于白接。提示符号表文件通常比较大上传需要一定时间建议把它加入发布流程的检查清单避免漏传。4. 实操过程与核心环节实现4.1 环境准备与工程导出配置先确认你的Unity版本和Android打包环境。Unity 2019及以上版本对Gradle的支持比较完善建议用这个区间以上的版本。Android SDK、NDK、JDK的版本要匹配尤其是NDK版本il2cpp编译对NDK版本有要求版本不对会直接编译失败。在Unity的Player Settings里把Publishing Settings下的Build勾选上Custom Main Gradle Template和Custom Gradle Properties Template这样导出工程后你可以直接改Gradle配置。Minimum API Level建议设成21或以上Target API Level根据应用商店要求设置一般设成最新的稳定版。导出工程时勾选Export Project而不是直接Build APK这样你会得到一个完整的Android Studio工程方便后续手动集成。导出完成后用Android Studio打开确认能正常编译通过再开始接SDK。这一步是基线如果导出工程本身编译不过先解决编译问题再往下走。4.2 集成Bugly SDK的完整步骤第一步在app模块的build.gradle里添加Bugly的依赖。通常是在dependencies块里加一行implementation具体坐标以官方文档为准。同时确认repositories里配置了对应的仓库地址否则依赖拉不下来。第二步在AndroidManifest.xml里添加权限声明。网络权限、网络状态权限、存储权限这三类是基础。如果你的应用还需要读取手机状态用于设备标识可能还需要额外的权限但Bugly较新版本已经尽量减少对敏感权限的依赖。第三步创建自定义的MainActivity。新建一个Java类继承UnityPlayerActivity在onCreate里调用super.onCreate之后紧接着调用Bugly的初始化方法。初始化方法需要传入App ID和一个配置对象配置对象里可以设置是否开启调试模式、是否上报native崩溃等。第四步修改AndroidManifest.xml里的启动Activity声明把原来的UnityPlayerActivity替换成你新建的这个类。注意intent-filter里的MAIN和LAUNCHER要保留。第五步写C#侧的桥接调用。在Unity的Assets目录下新建一个脚本用AndroidJavaClass加载你的桥接类封装几个静态方法供业务代码调用。比如上报自定义日志、设置用户ID、主动上报异常等。第六步编译打包安装到真机上测试。先测一个主动触发的异常看控制台能不能收到。再测一个native崩溃验证native捕获是否生效。4.3 关键配置参数的计算与选择初始化配置里有几个参数值得单独说一下。一个是上报间隔默认值一般是30秒左右意思是崩溃发生后不会立刻上报而是等下次启动或者间隔到了再上报。这个值设太小会增加网络请求频率和耗电设太大又会导致日志延迟。一般保持默认即可除非你有特殊需求。另一个是日志缓存大小。Bugly会在本地缓存一定量的日志缓存满了会覆盖旧日志。默认缓存大小对于一般应用够用但如果你的应用崩溃非常频繁可能需要调大缓存避免关键日志被冲掉。这个值在初始化配置里可以设置单位是字节。还有一个是是否捕获native崩溃。开启后会加载native库能捕获C层和引擎层的崩溃但会增加APK体积和少量性能开销。对于Unity项目我强烈建议开启因为Unity引擎本身的崩溃往往就是native崩溃不开的话你会漏掉很大一部分问题。4.4 验证接入是否成功的实操方法接入完成后怎么确认真的生效了我一般分三步验证。第一步主动上报一条测试日志。在C#里调用桥接类的上报方法传一条自定义日志然后去控制台看能不能查到。这一步验证的是C#到Java的桥接链路是否通畅。第二步在Java层主动抛一个未捕获异常。可以在自定义Activity里加一个测试按钮点击后抛RuntimeException。应用闪退后重新打开等一会儿去控制台看有没有这条崩溃记录。这一步验证的是Java层崩溃捕获是否生效。第三步触发一个native崩溃。这个稍微麻烦一点可以在native代码里故意写一个空指针解引用或者用Bugly提供的测试接口。验证的是native捕获链路。三步都通过基本可以确认接入完整。注意测试阶段建议开启调试模式这样控制台能实时看到上报日志方便排查。正式发布前记得关掉调试模式减少不必要的日志输出。5. 常见问题与排查技巧实录5.1 初始化失败与依赖冲突速查接入过程中最常见的问题就是初始化失败。表现是应用启动后控制台没有任何数据或者日志里出现初始化报错。排查思路可以按下面的表格来走。现象可能原因排查方法控制台无任何数据App ID错误或初始化未执行检查初始化代码是否被调用确认App ID初始化报ClassNotFound依赖未正确拉取检查build.gradle依赖和仓库配置初始化报权限不足权限未声明或被移除检查Manifest合并结果只有Java崩溃没有native崩溃native库未打包检查APK里是否有对应so库C#异常堆栈不全符号表未上传确认对应版本符号表已上传依赖冲突也是高频问题。Bugly依赖的某些基础库可能和你项目里已有的库版本不一致导致编译报错或者运行时行为异常。用gradlew app:dependencies可以查看依赖树找到冲突的库后用exclude排除掉旧版本或者用resolutionStrategy强制指定版本。5.2 崩溃日志不上的网络与策略问题有时候接入没问题但崩溃日志就是不上报。这种情况先排查网络。Bugly的上报需要网络连通如果应用在崩溃时正好没网日志会先缓存到本地等下次有网时再上报。所以测试时确保设备网络正常。如果网络正常还是不上报检查一下是不是触发了上报策略的限制。Bugly有每日上报次数限制和流量控制防止异常情况下疯狂上报。如果你的应用在短时间内大量崩溃可能会触发限流导致部分日志延迟上报。这个在控制台一般能看到相关提示。还有一种情况是应用被系统杀得太快崩溃发生后还没来得及写缓存就被杀了。这种在低内存设备上比较常见。可以在初始化时配置更积极的缓存策略但根本上还是要解决导致崩溃的代码问题。5.3 符号表上传与堆栈还原的实操细节符号表上传这件事我单独拿出来说因为它太容易被忽略了。上传的时机是在每次打包发布之后把对应版本的符号表文件传到Bugly控制台。符号表文件的位置在导出的Android工程目录下具体路径和Unity版本有关一般在symbols目录或者il2cpp相关目录里。上传工具是Bugly提供的命令行工具支持批量上传。建议把它集成到CI流程里每次打包自动上传避免人工遗漏。上传时要填对版本号版本号要和APK里的版本号一致否则控制台匹配不上。如果发现某个版本的崩溃堆栈是乱码或者只有地址没有函数名基本可以确定是符号表没传或者传错了版本。这时候补传符号表历史崩溃记录一般也能重新还原不用太担心。5.4 多线程与JNI调用的避坑经验前面提到过C#侧在子线程调用JNI需要先附加线程。具体做法是在调用前用AndroidJNI.AttachCurrentThread()调用完再DetachCurrentThread()。如果不做这一步轻则调用失败重则直接崩溃。另一个坑是JNI引用的管理。AndroidJavaObject创建的Java对象在C#侧是持有JNI引用的如果大量创建而不释放会导致JNI引用表溢出。对于频繁调用的场景建议复用对象或者用Dispose及时释放。还有一点Bugly的某些接口在应用退出过程中调用可能无效因为此时进程已经在销毁。所以不要在OnApplicationQuit里做关键的上报操作重要日志要在业务逻辑中及时上报不要攒到最后。5.5 版本升级与SDK维护的注意事项Bugly SDK会不定期更新修复bug或者适配新的Android版本。升级SDK时不要直接替换依赖版本就完事要看一下更新日志里有没有破坏性变更。比如某个版本改了初始化接口的签名你直接升级会编译不过。升级后要重新跑一遍验证流程确认崩溃捕获、日志上报、符号表还原都正常。尤其是native部分SDK升级可能涉及so库的更新要确认新so库和你的Unity版本兼容。另外如果你的项目同时接了其他崩溃采集或统计SDK要注意它们之间的兼容性。多个SDK同时注册信号处理器可能会互相干扰导致某些崩溃捕获不到。这种情况要么只保留一个要么确认它们的捕获机制不冲突。5.6 隐私合规与数据采集的边界最后提一个容易被忽视但很重要的点隐私合规。崩溃采集SDK会收集设备信息、系统信息、应用运行状态等数据这些在很多地区的隐私法规下属于需要告知用户并取得同意的范畴。接入之前要确认你的隐私政策里涵盖了这些采集行为并且在用户同意后再初始化SDK。Bugly本身提供了一些配置项可以控制是否采集某些信息比如是否获取设备标识。在合规要求严格的场景下可以关闭非必要的信息采集只保留崩溃堆栈这类核心数据。这个取舍要根据你的应用发布地区和目标用户群体来决定不能一刀切。我在实际项目里的做法是把SDK初始化放在用户同意隐私政策之后并且在隐私政策里明确列出采集的数据类型和用途。这样既满足了监控需求也避免了合规风险。这个经验分享出来希望对正在做上线准备的团队有点参考价值。