第30章 React Native Release 构建调试：符号化堆栈跟踪与 Source Maps 配置

版本：0.77 # 第30章 Debugging Release Builds · React Native 调试 Release 构建 ## 符号化堆栈跟踪 如果 React Native 应用在 release 构建中抛出未处理的异常，输出的信息可能被混淆而难以阅读。 07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119
上面的堆栈跟踪中，类似 p@1:132161 的条目是压缩后的函数名和字节码偏移量。要调试这些调用，我们需要把它们还原成文件名、行号和函数名，例如 AwesomeProject/App.js:54:initializeMap。这个过程叫做符号化（symbolication）。 你可以把堆栈跟踪和生成的 source map 一起传给 metro-symbolicate，来符号化上面这类压缩后的函数名和字节码。 ## 启用 source maps 符号化堆栈跟踪需要 source maps。请确保在目标平台的构建配置中启用了 source maps。 AndroidiOS Android 在 Android 上，source maps 默认是启用的。 要启用 source map 生成，请确保 android/app/build.gradle 中包含以下 hermesFlags 配置。 Groovy react {
hermesFlags = ["-O", "-output-source-map"]
}
配置正确的话，你会在 Metro 构建输出中看到 source map 的输出位置。 Text Writing bundle output to:, android/app/build/generated/assets/react/release/index.android.bundle
Writing sourcemap output to:, android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map
iOS 在 iOS 上，source maps 默认是禁用的。请按照以下步骤启用。 要启用 source map 生成： 打开 Xcode，编辑构建阶段 "Bundle React Native code and images"。 在其他 export 语句之上，添加一个 SOURCEMAP_FILE 条目，指定所需的输出路径。 Diff + export SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map"
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
操作正确的话，你应该能在 Metro 构建输出中看到 source map 的输出位置。 文本输出 bundle 写入位置：Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle Source map 输出写入位置：Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle.map 使用 metro-symbolicate 现在 source map 已生成，我们可以将堆栈追踪转换为可读信息。 # 打印使用说明 npx metro-symbolicate # 从包含堆栈追踪的文件中读取 npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt # 从 adb logcat（Android）中读取 adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map 关于 source map 的注意事项 构建过程可能会生成多个 source map。请务必使用示例中显示位置的对应文件。 请确认所使用的 source map 与崩溃 app 的提交版本（commit）完全一致。源代码的细微改动都可能导致偏移量产生巨大差异。 如果 metro-symbolicate 立即退出并显示成功，请确认输入来自管道或重定向，而非直接输入终端。