文档
BlogChangelogStar Us on GitHub
首页指南EASReferenceLearn
存档Expo SnackDiscord and forums新闻邮件

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

Expo Router 集成

编辑页面

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

EAS Observe 为 Expo Router 提供了一个可选集成，用于收集按路由标记的每路由指标（例如 /(tabs)/sessions/[sessionId]）。这样你就可以在仪表盘中按路由比较导航性能，而不只是查看应用整体汇总。

前提条件

Prerequisites

3 requirements

1.

Expo SDK 56 或更高版本

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

2.

应用中已使用 EAS Observe

按照 开始使用 安装 expo-observe 并创建你的第一个 构建。

3.

应用中已安装 Expo Router

该集成在运行时依赖 expo-router。如果未安装该包，集成将静默地不执行任何操作。

1

启用集成

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

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

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

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

2

在你的屏幕中调用 useObserve()

使用 useObserve() Hook 获取一个会自动限定到当前路由的 markInteractive。发出的事件会附带该屏幕的路由模式标签。

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 (/* 你的屏幕内容 */);
}

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

过滤敏感的 URL 参数

在 SDK 57 及更高版本中可用。

默认情况下，该集成会将解析后的 url 以及 routeParams 中所有可序列化的路由参数和查询参数都包括在内。如果应用在 URL 参数中包含敏感值，请将其键传递给 filteredParams：

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

Observe.configure({
  integrations: {
    'expo-router': {
      filteredParams: ['userId', 'token'],
    },
  },
});

该集成会从 routeParams 中移除经过过滤的键，并且事件会省略 url，改为包含 urlHidden: true。routeName 不受影响，因为它是一个模式，从不包含参数值。

指标

按路由首屏渲染（cold_ttr）

衡量内容： 从发出导航动作（例如点击链接）到目标屏幕第一次获得焦点所用的时间。对于应用启动后的第一次聚焦，测量从 JS bundle 加载开始计算，并且事件包含 isAppLaunch: true。

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

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring导航解析后的路径名。
urlHiddenboolean当由于过滤了某个参数而省略 url 时，该值为 true。
routeParamsobject解析后的路由参数（例如 { sessionId: 'abc' }）。
isAppLaunchboolean根据进程启动进行测量时为 true，后续导航时为 false。

按路由热渲染（warm_ttr）

衡量内容： 与 cold_ttr 相同，但适用于在获得焦点之前已经渲染过的屏幕，通常是因为它们通过 <Link prefetch /> 预加载，或者用户返回到了这些屏幕。

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring导航解析后的路径名。
urlHiddenboolean当由于过滤了某个参数而省略 url 时，该值为 true。
routeParamsobject解析后的路由参数（例如 { sessionId: 'abc' }）。

按路由可交互时间（tti）

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

事件参数：

参数类型描述
routeNamestring路由模式，例如 /(tabs)/sessions/[sessionId]。
urlstring解析后的路径名。
urlHiddenboolean当由于过滤了某个参数而省略 url 时，该值为 true。
routeParamsobject解析后的路由参数。
...any通过 markInteractive({ params: { ... } }) 传递的任何自定义参数。

说明与故障排查

  • 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 的常规问题，请参阅 故障排查。