This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

记录你应用中的 JavaScript 错误和原生崩溃，并在 EAS Observe 仪表板里查看堆栈跟踪。

重要 EAS Observe 的错误报告处于预览状态，需要 SDK 57 或更高版本。原生崩溃还需要 expo-observe 57.0.21 或更高版本。EAS Update 的源映射和更多内容仍在开发中。

expo-observe 库会记录你应用中的 JavaScript 错误和原生崩溃，同时跟踪性能指标。错误会保存在设备上，进行批量处理，并在下一次刷新时发送。你可以在 EAS Observe 仪表板的 Errors 页面看到这些错误。

🌐 The expo-observe library records JavaScript errors and native crashes from your app alongside its performance metrics. Errors are persisted on-device, batched, and dispatched on the next flush. They appear in the Errors page of the EAS Observe dashboard.

JavaScript 错误

🌐 JavaScript errors

JavaScript 错误有三种途径被捕获：未处理的错误会自动记录，渲染错误会被 ObserveErrorBoundary 捕获，而已处理的错误可以通过 Observe.reportError 上报。

🌐 JavaScript errors are captured through three paths: unhandled errors are recorded automatically, render errors are caught by ObserveErrorBoundary, and handled errors can be reported with Observe.reportError.

未处理的错误

🌐 Unhandled errors

未处理的 JavaScript 错误会自动记录。该库在第一次导入时会安装一个全局错误处理程序，所以不需要额外设置。React Native 自身的行为不会改变：在开发环境中仍会显示红框，严重错误仍会在生产环境中终止应用。

🌐 Unhandled JavaScript errors are recorded automatically. The library installs a global error handler when it is first imported, so no setup is required. React Native's own behavior is unchanged: the red box still appears in development, and fatal errors still terminate the app in production.

要关闭自动录音，通过 configure() 将 errorHandlingEnabled 设置为 false：

🌐 To turn off automatic recording, set errorHandlingEnabled to false via configure():

import { Observe } from 'expo-observe';

Observe.configure({
  errorHandlingEnabled: false,
});

这只会影响未处理的 JavaScript 错误。通过 ObserveErrorBoundary 捕获的错误、通过 Observe.reportError 报告的错误以及本地崩溃仍然会被记录。

🌐 This only affects unhandled JavaScript errors. Errors caught by ObserveErrorBoundary, errors reported with Observe.reportError, and native crashes are still recorded.

渲染错误

🌐 Render errors

如果没有错误边界，在渲染时抛出的错误会被全局错误处理器记录为未处理的错误。用 ObserveErrorBoundary 封装子树，可以将错误和 React 组件堆栈一起记录，并在抛出错误的子树位置显示一个备用 UI:

🌐 Without an error boundary, an error thrown while rendering is recorded by the global error handler as an unhandled error. Wrap a subtree with ObserveErrorBoundary to record it together with the React component stack and show a fallback UI in place of the subtree that threw:

import { ObserveErrorBoundary } from 'expo-observe';

export default function FeedScreen() {
  return (
    <ObserveErrorBoundary
      fallback={({ error, resetError }) => <ErrorScreen error={error} onRetry={resetError} />}>
      <Feed />
    </ObserveErrorBoundary>
  );
}

fallback 属性可以接受一个 React 元素、null，或者一个接收抛出的 error 和 resetError 回调的函数。调用 resetError() 会清除捕获的错误并重新挂载子组件，让它们从干净的状态重新开始。

🌐 The fallback prop accepts a React element, null, or a function that receives the thrown error and a resetError callback. Calling resetError() clears the caught error and re-mounts the children, so they restart from a clean state.

要在整个应用周围设置边界，请将 errorBoundaryFallback 传递给 ObserveRoot 组件，而不是手动去封装它：

🌐 To place a boundary around your whole app, pass errorBoundaryFallback to the ObserveRoot component instead of wrapping it manually:

import { ObserveRoot } from 'expo-observe';

export default function RootLayout() {
  return (
    <ObserveRoot errorBoundaryFallback={<FallbackScreen />}>
      <Stack />
    </ObserveRoot>
  );
}

即使没有边界捕捉到的渲染错误，全球错误处理程序仍然会记录它们。

🌐 Render errors that no boundary catches are still recorded by the global error handler.

已处理的错误

🌐 Handled errors

你的代码捕获并恢复的错误不会到达全局处理器或错误边界。用 Observe.reportError 报告它们：

🌐 Errors your code catches and recovers from reach neither the global handler nor an error boundary. Report them with Observe.reportError:

import { Observe } from 'expo-observe';

async function handleSync() {
  try {
    await syncCart();
  } catch (error) {
    Observe.reportError(error);
  }
}

reportError 可以接受任何抛出的值。Error 会提供它的名字、信息和堆栈跟踪。任何其他值（字符串、普通对象、数字）都会被转换为信息字符串，但没有堆栈跟踪。

在错误信息中避免使用个人可识别信息（PII）。你报告的所有内容都会显示在仪表板上，并会从设备之外发送出去。

🌐 Avoid Personally Identifiable Information (PII) in error messages. Everything you report is visible in the dashboard and is dispatched off-device.

本地崩溃

🌐 Native crashes

本地崩溃会在你的 JavaScript 做出反应之前就终止应用，所以报告会先写入设备，并在下次应用启动时发送。Android 和 iOS 上的本地崩溃会在 expo-observe 57.0.21 或更高版本中自动记录，无需任何设置。在仪表盘上，它们会以 Native 来源显示。

🌐 A native crash terminates the app before your JavaScript can react to it, so the report is written on the device and dispatched the next time the app launches. Native crashes are recorded automatically on Android and iOS with expo-observe 57.0.21 or later, and no setup is required. They appear with the Native source in the dashboard.

在安卓上，EAS Observe 会记录未捕获的 Java 和 Kotlin 异常，包括 Caused by 链。在安卓 11 及更高版本上，它还会读取操作系统为你的应用保留的崩溃记录，这些记录涵盖了原生代码中的崩溃，例如 SIGSEGV 和 SIGABRT。

🌐 On Android, EAS Observe records uncaught Java and Kotlin exceptions, including the Caused by chain. On Android 11 and later, it also reads the crash records the operating system keeps for your app, which covers crashes in native code such as SIGSEGV and SIGABRT.

在 iOS 上，EAS Observe 使用 MetricKit 来收集系统为你的应用生成的崩溃报告。这些报告涵盖了 Mach 异常，比如 EXC_BAD_ACCESS 和 EXC_BREAKPOINT，以及 Unix 信号，比如 SIGSEGV、SIGBUS 和 SIGTRAP。在 iOS 17 及更高版本上，它们还涵盖了未捕获的 Objective-C 和 Swift 异常。

🌐 On iOS, EAS Observe uses MetricKit to collect the crash reports the system produces for your app. These cover Mach exceptions such as EXC_BAD_ACCESS and EXC_BREAKPOINT, and Unix signals such as SIGSEGV, SIGBUS, and SIGTRAP. On iOS 17 and later, they also cover uncaught Objective-C and Swift exceptions.

注意： 在 tvOS 或 iOS 模拟器上不会记录原生崩溃。应用无响应（ANR）事件和内存不足导致的终止也不会在这两个平台上记录。

调查一个错误

🌐 Investigate an error

点击列表中的错误以查看详细信息。页面会显示错误出现的频率、受影响的用户数量、首次和最近一次出现的时间，以及在不同平台上的分布情况。

🌐 Click an error in the list to open its details. The page shows how often the error occurs, how many users it affects, when it was first and last seen, and how it splits across platforms.

在摘要下面，发生情况 会逐条展示各个报告，每条都会显示它来自的应用版本、设备和操作系统。堆栈跟踪 显示所选发生情况的帧，而 崩溃前 列出导致崩溃的最后一次会话记录。打开 会话时间线 可查看完整会话。使用 细分 部分可以看到错误影响了哪些应用版本、操作系统、设备和国家，点击某个数值可以按它来过滤页面。

🌐 Below the summary, Occurrence steps through the individual reports one at a time, each with the app version, device, and OS it came from. Stack trace shows the frames for the selected occurrence, and Before the crash lists the last session records that preceded it. Open Session timeline to see the full session. Use the Breakdown section to see which app versions, operating systems, devices, and countries the error affects, and click a value to filter the page by it.

发生情况 标签列出了组中的每个报告，因此你可以查看错误出现在的版本和设备。

🌐 The Occurrences tab lists every report in the group, so you can scan the versions and devices an error appears on.

交给人工智能

🌐 Hand off to AI

在错误详情页面选择 交给 AI 处理，就可以开始让编码助手调查错误。它会准备一个提示，描述错误、堆栈跟踪、当前应用的过滤器，以及按版本、操作系统、设备和国家的分类。你可以直接把提示发送给 Claude Code 或 Codex，或者复制后粘贴到其他助手里。

🌐 Select Hand off to AI on the error details page to start investigating the error with a coding agent. It prepares a prompt that describes the error, its stack trace, the filters currently applied, and the breakdown by version, OS, device, and country. Send the prompt straight to Claude Code or Codex, or copy it and paste it into another assistant.

这个代理使用提示将堆栈跟踪映射到你的源代码上，并使用 eas observe: 命令获取更多上下文信息，比如崩溃来自哪个会话。

🌐 The agent uses the prompt to map the stack trace onto your source and to pull more context with the eas observe: commands, such as the session the crash came from.

符号化堆栈追踪

🌐 Symbolicated stack traces

在生产环境的应用中，你的 JavaScript 会被打包和压缩。堆栈追踪显示的是生成的包里的行和列位置，而不是你的源文件。源映射（source map）可以把这些位置翻译回源代码中的位置。当为某个构建存储源映射时，控制面板会显示每一帧的原始文件、行和列，并在堆栈追踪旁边标出错误所在的构建。

🌐 In a production app, your JavaScript is bundled and minified. Stack traces point at line and column positions in the generated bundle, not in your source files. A source map translates those positions back. When a source map is stored for a build, the dashboard shows the original file, line, and column for each frame, and links the build the error came from next to the stack trace.

如果构建没有存储源映射，仪表板会原样显示报告的堆栈跟踪。这样的话，帧就会引用压缩包里的位置，比如 index.android.bundle:1:481231，很难对应回你的代码。

🌐 If no source map is stored for the build, the dashboard shows the reported stack trace as-is. Frames then reference positions in the minified bundle, such as index.android.bundle:1:481231, and are difficult to map back to your code.

使用 EAS 构建上传源映射

🌐 Upload source maps with EAS Build

要为每次构建存储源映射，请在 eas.json 的构建配置中将 uploadSourceMaps 设置为 true：

🌐 To store a source map for each build, set uploadSourceMaps to true in the build profile in eas.json:

{
  "build": {
    "production": {
      "uploadSourceMaps": true
    }
  }
}

有了这个设置，EAS Build 会上传在打包你应用的 JavaScript 时生成的源地图。这样，每个从该构建报告的错误都可以进行符号化。你的应用代码无需做任何更改。

🌐 With this setting, EAS Build uploads the source map produced when your app's JavaScript is bundled. Symbolication then works for every error reported from that build. No changes to your app code are required.

注意：上传源映射需要 EAS CLI 版本 22.0.0 或更高，并且仅适用于在 EAS Build 服务器上运行的构建。使用 eas build --local 创建的本地构建不会上传源映射。

源映射（sourcesContent）中嵌入的源代码在上传前会被移除。只会存储文件名和位置映射。如果上传失败，构建仍然会完成，并在构建日志中显示一个警告。

🌐 The source code embedded in the source map (sourcesContent) is removed before upload. Only file names and position mappings are stored. If the upload fails, the build still completes and shows a warning in the build logs.

本地堆栈跟踪

🌐 Native stack traces

源映射只适用于 JavaScript。本地堆栈跟踪在仪表板中不会被符号化。

🌐 Source maps only apply to JavaScript. Native stack traces are not symbolicated in the dashboard.

在 Android 上，Java 和 Kotlin 异常的栈帧已经包含了类、方法和行号。在 iOS 上，栈帧会在发生崩溃的设备上解析为符号名，所以你只能看到函数名，但看不到文件名或行号。无法解析的栈帧会显示为二进制名称和偏移量，比如 MyApp + 19160。

🌐 On Android, frames from Java and Kotlin exceptions already carry the class, method, and line number. On iOS, frames are resolved to symbol names on the device where the crash happened, so you see function names but no file names or line numbers. A frame that cannot be resolved is shown as a binary name and an offset, such as MyApp + 19160.

查看错误

🌐 View errors

打开你的项目，然后导航到 观察 > 错误。

🌐 Open your project and navigate to Observe > Errors.

无崩溃会话卡片显示在选定时间范围内没有发生致命错误的会话占比。它还显示无崩溃用户、致命和非致命错误数量，以及受影响的用户数。

🌐 The Crash-free sessions card shows the share of sessions in the selected time range that finished without a fatal error. It also shows crash-free users, fatal and non-fatal counts, and the number of affected users.

不同错误 列出了所选时间范围内记录的错误，并按错误类型分组。来源 列告诉你错误的出处：

按来源、严重性（致命或非致命）、平台、环境和版本来筛选列表。致命错误会在应用下次启动时报告，所以最近的崩溃可能需要一些时间才会显示。

🌐 Filter the list by source, by severity (Fatal or Non-fatal), by platform, by environment, and by release. Fatal errors are reported on the app's next launch, so a recent crash can take time to appear.

还有待发生

🌐 Still to come

错误报告正在预览中，以下功能尚不可用：

🌐 Error reporting is in preview, and the following are not available yet:

• EAS 更新的源映射：运行 OTA 更新的应用出现的错误显示了未符号化的堆栈跟踪。
• 本地崩溃的符号化：目前还不支持上传调试符号，比如 Android 的 ProGuard 映射和 iOS 的 dSYM。