中文网
🌐 Nodejs.cn
首页指南EAS参考学习

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

Expo 路由集成

通过启用 EAS Observe 的 Expo Router 集成来跟踪每个路由的渲染和交互时间。

EAS Observe ships 是一个针对 Expo Router 的可选集成，它会收集按路由模式标记的每个路由的指标（例如，/(tabs)/sessions/[sessionId]）。这让你可以在仪表板中按路由比较导航性能，而不仅仅是查看整个应用的汇总数据。

🌐 EAS Observe ships an opt-in integration for Expo Router that collects per-route metrics tagged with the route pattern (for example, /(tabs)/sessions/[sessionId]). This lets you compare navigation performance by route in the dashboard instead of looking only at app-wide aggregates.

先决条件

🌐 Prerequisites

先决条件

3 要求

1.

Expo SDK 56 或更高版本

Expo Router 集成可在 SDK 56 及更高版本使用。在较早的 SDK 上，expo-observe 仍会跟踪全应用的指标，但不会发出按路由的导航事件。

2.

一个已经使用 EAS 观察的应用

按照 入门指南 安装 expo-observe 并创建你的第一个构建。

3.

Expo 路由已安装在应用中

该集成在运行时依赖 expo-router。如果未安装该包，集成将默默无效。

1

启用集成

🌐 Enable the integration

警告 集成必须在挂载前启用，且不能在运行时切换。在应用挂载后调用 configure()，或在会话中途切换标志，会抛出错误。

在任何屏幕挂载之前，在模块作用域内使用 expo-router 集成标志调用 Observe.configure()：

🌐 Call Observe.configure() with the expo-router integration flag at module scope, before any screen mounts:

src/app/_layout.tsx
import { Observe } from 'expo-observe';

Observe.configure({
  integrations: { 'expo-router': true },
});

2

在你的屏幕中调用 useObserve()

🌐 Call useObserve() in your screens

使用 useObserve() 钩子来获取一个自动绑定到当前路由的 markInteractive。发出的事件会被标记为屏幕的路由模式。

🌐 Use the useObserve() hook to get a markInteractive that is automatically scoped to the current route. The emitted event is tagged with the screen's route pattern.

src/app/(tabs)/index.tsx
import { useObserve } from 'expo-observe';
import { useEffect } from 'react';

export default function Home() {
  const { markInteractive } = useObserve();

  useEffect(() => {
    markInteractive();
  }, [markInteractive]);

  return (/* your screen content */);
}

信息 如果集成被禁用或未安装 expo-router，useObserve() 将回退到全局 Observe.markInteractive。无论集成状态如何，你都可以保留该钩子。

指标

🌐 Metrics

每路由首次渲染（cold_ttr）

🌐 Per-route first render (cold_ttr)

它衡量的内容： 从导航操作被触发（例如点击链接）到目的屏幕首次获得焦点的时间。对于应用启动后的第一次焦点，测量从 JS 包加载时开始，该事件包括 isAppLaunch: true。

在一次会话中的每个屏幕实例最多发出一次。

🌐 Emitted at most once per screen instance within a session.

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring导航的解析路径名。
routeParamsobject解析后的路由参数（例如 { sessionId: 'abc' }）。
isAppLaunchboolean相对于进程启动时的 true，后续导航为 false。

每路预热渲染（warm_ttr）

🌐 Per-route warm render (warm_ttr)

它的衡量指标: 与 cold_ttr 相同，但针对那些在获取焦点之前已经渲染的屏幕，通常是因为它们通过 <Link prefetch /> 预加载，或用户导航回到它们。

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring导航的已解析路径名。
routeParamsobject已解析的路由参数（例如，{ sessionId: 'abc' }）。

每条路由到可交互的时间（tti）

🌐 Per-route time to interactive (tti)

它测量的内容： 从导航操作被分发到目标屏幕上调用 markInteractive() 的时间。每次导航只记录第一次调用，因此可以安全地多次调用 markInteractive()。

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring已解析的路径名。
routeParamsobject已解析的路由参数。
...any通过 markInteractive({ params: { ... } }) 传入的任何自定义参数。

注意事项与故障排除

🌐 Notes and troubleshooting

  • routeName 是一个模式（/(tabs)/sessions/[sessionId]），而不是已解析的 URL（/sessions/abc）。这样可以在不同的参数值之间保持指标的稳定，因此仪表板会将它们归为一类。解析后的值仍然可以通过 url 和 routeParams 在事件中获取。
  • 对 router.prefetch() 的调用不计为用户导航，也从不触发 cold_ttr 或 warm_ttr 测量。下一次用户驱动的到该路由的导航会触发 warm_ttr，因为屏幕已经渲染。
  • 该集成仅在运行时安装了 expo-router 时才会激活。如果未安装，useObserve() 和 ObserveRoot 将继续工作，但不会发出每条路由的导航指标。
  • 必须在通过 Observe.configure({ integrations: { 'expo-router': true } }) 挂载之前启用该集成。应用挂载后切换它会抛出错误。
  • 如果 markInteractive() 记录了 Calling markInteractive on unmounted screen 或 No metadata available for the current screen，则表示该调用在屏幕组件之外或卸载后运行。将调用移到屏幕组件内的 useEffect 中。
  • 有关 EAS Observe 的一般问题，请参阅 故障排除。