企业官网建设流程全解析

react-native-fabric 是一个将 Fabric、Crashlytics 和 Answers 能力接入 React Native 应用的桥接库。它的recordCustomExceptionName方法可以把 JS 侧捕获的异常名、原因和堆栈帧完整上报到 Crashlytics 控制台，是定位"业务逻辑异常但 App 未崩溃"这类问题的关键能力。本文带你从 JS 入口一路读到原生实现，讲清楚自定义 JS 堆栈追踪的实现原理。

为什么需要自定义 JS 堆栈追踪 🤔

Crashlytics 天然擅长捕获原生崩溃（Native Crash），但 React Native 应用里很多错误发生在 JS 层：

• Promise 里 catch 到的业务异常，App 并不会崩溃；
• 异步逻辑抛错后 JS 堆栈被截断，只剩一行报错信息；
• 想主动"软上报"一个异常，却不想真的让 App 闪退。

这时候就需要自定义异常上报：把error.name、error.message和手工收集到的 JS 堆栈帧（文件、函数、行号）传给原生层，让 Crashlytics 按"一条崩溃记录"来展示和分组。

recordCustomExceptionName正是干这件事的 API，它的类型签名定义在 typings/react-native-fabric.d.ts：

recordCustomExceptionName(name: string, reason: string, frameArray: Array<Object>): void

整体架构：JS → Bridge → Native 三跳 🌉

一次调用会经过三层，各层职责非常清晰：

JS 入口：一行代码的防御式设计

JS 侧的实现在 src/Crashlytics.js 中，核心就一句：

SMXCrashlytics.recordCustomExceptionName(name, reason, stack || []);

这里有个值得注意的细节：第三个参数stack是可选的，调用方不传堆栈时会自动兜底为空数组[]。这样原生层拿到的永远是一个数组，不会因为undefined而在桥接层报错——这对跨语言 RPC 来说是很典型的防御式写法。

每个堆栈帧约定为这样的对象结构（两端原生代码共同解析的字段）：

• functionName：函数名
• fileName：源文件名
• lineNumber：行号
• columnNumber：列号（目前仅 iOS 端使用）

Android 实现原理：借 logException 完成"伪装" ⚙️

Android 端的实现在 SMXCrashlytics.java 中，逻辑分三步：

1. 逐帧转换：遍历 JS 传来的ReadableArray，把每一帧 Map 读取出functionName、fileName、lineNumber，构造 Android 原生的StackTraceElement；缺失的函数名会兜底为"Unknown Function"，缺失的行号兜底为-1；
2. 拼装异常：new Exception(name + "\n" + reason)，将异常名和原因拼接为异常消息；
3. 替换堆栈并上报：调用e.setStackTrace(stackTrace)把 JS 堆栈"贴"到这个异常对象上，再交给Crashlytics.logException(e)上报。

💡 这里有一个关键设计取舍：Android 版 Fabric SDK没有提供recordCustomExceptionName这个原生方法，作者用logException+ 手工设置StackTrace的方式模拟出了等价效果——用户在控制台看到的仍然是一条带自定义名称和 JS 堆栈的异常记录。

iOS 实现原理：直通原生 API 的路径 🍎

iOS 端走的是更"正统"的路线。SMXCrashlytics.m 中的处理：

1. 遍历 JS 传来的帧数组，为每帧创建CLSStackFrame对象（定义见 CLSStackFrame.h）；
2. 字段一一映射：fileName→ 文件名、lineNumber→ 行号、columnNumber→offset（偏移量）、functionName→symbol（符号）；
3. 最终调用 Crashlytics 官方原生接口recordCustomExceptionName:reason:frameArray:完成上报。

CLSStackFrame头文件注释里明确说：这些字段都会展示在 Crashlytics 控制台上，并可能影响崩溃的自动分组——这就是为什么帧数据的质量（真实文件路径、准确行号）对排查效率影响很大。

平台差异一览表 📊

可以看到两端虽然路径不同，但都遵循"JS 帧数组 → 原生帧对象 → Crashlytics 上报"的统一模型，调用方无需关心平台差异。

实际使用：把 JS 堆栈传上去 ✍️

典型用法是在try/catch或 Promise 的catch中，从Error对象解析出堆栈字符串，切分成帧后逐个上报。每个帧对象只需提供上面约定的三个关键字段（columnNumber可选），即可在 Crashlytics 控制台看到形如"文件名 + 函数名 + 行号"的 JS 堆栈。

小提示：上报的name建议带上业务前缀（如Biz-Login），方便在控制台按异常名快速筛选和聚合。

总结：一张图看懂调用链 ✅

JS: Crashlytics.recordCustomExceptionName(name, reason, stack) │ NativeModules 桥接（stack 缺省兜底为 []） ├──► Android: ReadableArray → StackTraceElement[] │ → new Exception(name + "\n" + reason) │ → setStackTrace → Crashlytics.logException └──► iOS: NSArray → CLSStackFrame[] → Crashlytics recordCustomExceptionName:reason:frameArray:

理解recordCustomExceptionName的实现原理，核心就是记住三点：

1. JS 层做防御：堆栈参数可选、缺省兜底，保证桥接层永远收到合法数组；
2. Android 层做模拟：用logException+setStackTrace拼出等效的自定义异常记录；
3. iOS 层做直连：逐帧转换为CLSStackFrame，调用 Crashlytics 官方 API。

掌握这套"帧对象 → 原生帧 → 上报"的模型后，你在其他 React Native 埋点/监控场景中（比如自定义 Analytics 事件）也会遇到完全相同的跨平台设计思路。