错误处理和加载状态

学习在使用 Expo Router 时如何处理应用中的未匹配路由、错误和加载状态。

本指南说明了在使用 Expo Router 时如何处理应用中的未匹配路由、错误和加载状态。

🌐 This guide specifies how to handle unmatched routes, errors, and loading states in your app when using Expo Router.

未匹配的路由

🌐 Unmatched routes

原生应用没有服务器，所以从技术上讲不存在 404 错误。然而，如果你在全局实现路由，那么处理缺失的路由是有意义的。这对于每个应用都是自动补齐的，但你也可以进行自定义。

🌐 Native apps don't have a server so there are technically no 404s. However, if you're implementing a router universally, then it makes sense to handle missing routes. This is done automatically for each app, but you can also customize it.

src/app/+not-found.tsx

import { Unmatched } from 'expo-router';
export default Unmatched;

这将渲染默认的 Unmatched。你可以导出任何你想渲染的组件。我们建议提供一个指向 / 的链接，这样用户可以返回主屏幕。

🌐 This will render the default Unmatched. You can export any component you want to render instead. We recommend having a link to / so users can navigate back to the home screen.

路由优先级

🌐 Route priority

在网页端，文件按以下顺序提供：

🌐 On web, files are served in the following order:

public 目录中的静态文件。
应用目录中的标准和动态路由。
应用目录中的 API 路由。
未找到的路由将最后返回 404 状态码。

错误处理

🌐 Error handling

Expo Router 支持微调错误处理，以便在未来实现更加有态度的数据加载策略。

🌐 Expo Router enables fine-tuned error handling to enable a more opinionated data-loading strategy in the future.

Using ErrorBoundary in Expo Router to catch errors in a route component.

你可以从任何路由导出嵌套的 ErrorBoundary 组件，以使用 React 错误边界拦截并格式化组件级错误：

🌐 You can export a nested ErrorBoundary component from any route to intercept and format component-level errors using React Error Boundaries:

src/app/home.tsx

import { View, Text } from 'react-native';
import { type ErrorBoundaryProps } from 'expo-router';

export function ErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return (
    <View style={{ flex: 1, backgroundColor: "red" }}>
      <Text>{error.message}</Text>
      <Text onPress={retry}>Try Again?</Text>
    </View>
  );
}

export default function Page() { ... }

当你导出一个 ErrorBoundary 时，该路由将被一个 React 错误边界有效地封装：

🌐 When you export an ErrorBoundary the route will be wrapped with a React Error Boundary effectively:

Virtual

function Route({ ErrorBoundary, Component }) {
  return (
    <Try catch={ErrorBoundary}>
      <Component />
    </Try>
  );
}

当 ErrorBoundary 不存在时，错误将被抛到最近的父级 ErrorBoundary，并接受 error 和 retry 属性。

🌐 When ErrorBoundary is not present, the error will be thrown to the nearest parent's ErrorBoundary and accepts error and retry props.

布局中屏幕的错误边界

🌐 Error boundaries for screens in a layout

屏幕错误边界在屏幕出现异常时会保持导航器的界面（比如标题栏和标签栏）挂载。可以在布局或导航器上进行配置：

🌐 A screen error boundary keeps navigator UI, such as headers and tab bars, mounted when a screen throws. Configure it on a layout or navigator:

src/app/_layout.tsx

import { Stack, type ErrorBoundaryProps } from 'expo-router';
import { Text } from 'react-native';

function ScreenErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return <Text onPress={retry}>Try again: {error.message}</Text>;
}

// Configure the boundary for screens in this layout and nested layouts.
export const unstable_settings = {
  screenErrorBoundary: ScreenErrorBoundary,
};

export default function Layout() {
  return <Stack />;
}

或者，在导航器上配置边界：

🌐 Alternatively, configure the boundary on the navigator:

src/app/_layout.tsx

import { Stack, type ErrorBoundaryProps } from 'expo-router';
import { Text } from 'react-native';

function ScreenErrorBoundary({ error, retry }: ErrorBoundaryProps) {
  return <Text onPress={retry}>Try again: {error.message}</Text>;
}

// This prop overrides unstable_settings.screenErrorBoundary for the same screens.
export default function Layout() {
  return <Stack unstable_screenErrorBoundary={ScreenErrorBoundary} />;
}

Expo Router 按以下顺序应用错误边界：

🌐 Expo Router applies error boundaries in the following order:

ErrorBoundary 已从屏幕导出
导航器级别属性（例如，Stack）
unstable_settings.screenErrorBoundary 声明在 _layout.tsx 文件中

嵌套布局会继承 unstable_settings.screenErrorBoundary，除非它们定义了自己的屏幕错误边界。在嵌套布局中将 screenErrorBoundary 设置为 null 可以停止继承它。

🌐 Nested layouts inherit unstable_settings.screenErrorBoundary unless they define their own screen error boundary. Set screenErrorBoundary to null in a nested layout to stop inheriting it.

尚未完成的

🌐 Work in progress

React Native LogBox 需要以不那么激进的方式渲染，以便在有错误时继续开发。目前，它会在 console.error 和 console.warn 上显示。然而，理想情况下，它应该只在未捕获的错误上显示。

🌐 React Native LogBox needs to be presented less aggressively to develop with errors. Currently, it shows for console.error and console.warn. However, it should ideally only show for uncaught errors.

使用 Suspense 回退的加载状态

🌐 Loading states with Suspense fallback

重要自定义 suspense 后备在 SDK 56 及更高版本中可用。

在 SDK 58 及更高版本中，异步路由在 Web 上默认启用，并使用默认的加载回退，而不是自定义的 SuspenseFallback 导出。要在 Web 上使用下面的示例，请在你的应用配置的 expo-router 配置插件中设置 asyncRoutes: { web: false }。这将恢复同步路由加载和自定义回退支持。原生默认设置保持不变。

🌐 In SDK 58 and later, async routes are enabled by default on web and use the default loading fallback instead of custom SuspenseFallback exports. To use the examples below on web, set asyncRoutes: { web: false } in the expo-router config plugin in your app config. This restores synchronous route loading and custom fallback support. Native defaults are unchanged.

Expo Router 会将每条路由封装在一个 React Suspense 边界中。你可以从布局文件中导出一个 SuspenseFallback 组件，以自定义在任何子路由被挂起时显示的加载界面：

🌐 Expo Router wraps each route in a React Suspense boundary. You can export a SuspenseFallback component from a layout file to customize the loading UI shown while any child route is suspended:

src/app/_layout.tsx

import { ActivityIndicator, View } from 'react-native';
import { Stack } from 'expo-router';

export function SuspenseFallback() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <ActivityIndicator size="large" />
    </View>
  );
}

export default function RootLayout() {
  return <Stack />;
}

当多个父布局定义了回退时，最近的父布局优先。

访问路由参数

🌐 Accessing route parameters

[SuspenseFallback](/versions/latest/sdk/router/#suspensefallback) 组件接收 route 和 params 属性。你可以使用 params 来显示动态路由的特定上下文加载状态，例如：

🌐 The SuspenseFallback component receives route and params props. You can use params to display context-specific loading states for dynamic routes, for example:

src/app/(app)/_layout.tsx

import { ActivityIndicator, Text, View } from 'react-native';
import { Stack, type SuspenseFallbackProps } from 'expo-router';

export function SuspenseFallback({ params }: SuspenseFallbackProps) {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Loading profile {params.id}...</Text>
      <ActivityIndicator size="large" />
    </View>
  );
}

export default function AppLayout() {
  return <Stack />;
}

局限性

🌐 Limitations

异步路由不支持自定义 Suspense 回退。