文档
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.

设置 EAS Observe

编辑页面

了解如何安装 EAS Observe，并开始从你的生产应用中收集性能指标。

使用 AI agent 设置 EAS Observe

将此内容粘贴到 Claude、Cursor、Codex 或其他 agent 中。

EAS Observe 跟踪你的应用在生产环境中的启动性能。本指南将带你完成库的安装、应用的设置，以及查看你的第一个指标。

重要 EAS Observe 在 Expo Go 中不可用，因为它依赖于 expo-observe 原生库。要使用它，请创建一个开发构建或生产构建。

先决条件

Prerequisites

3 requirements

1.

Expo 用户账号

任何拥有 Expo 账号的人都可以使用 EAS Observe。你可以在 expo.dev/signup 注册。

2.

Expo SDK 55 或更高版本

EAS Observe 需要 SDK 55 或更高版本。运行 npx expo-doctor 检查你的 SDK 版本，并运行 npx expo install --fix 更新依赖。

3.

EAS 项目

你的应用必须已关联到一个 EAS 项目。请确保应用配置中的 extra.eas.projectId 包含项目 ID，或者通过运行 eas init 创建一个。

1

安装库

请确保你使用的是最新版本的 expo，然后安装 expo-observe：

Terminal
- npx expo install --fix

- npx expo install expo-observe
- yarn expo install --fix

- yarn expo install expo-observe
- pnpm expo install --fix

- pnpm expo install expo-observe
- bun expo install --fix

- bun expo install expo-observe

2

包裹你的根布局

使用 AppMetricsRoot（SDK 55）或 ObserveRoot（SDK 56 及更高版本）包裹你的根布局。这个高阶组件（HOC）会自动为你测量首次渲染时间（TTR）。

app/_layout.tsx
import { Stack } from 'expo-router';
import { ObserveRoot } from 'expo-observe';

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

export default ObserveRoot.wrap(RootLayout);

3

标记为可交互

当你的应用完全准备好接受用户交互时，调用 markInteractive()。这应该在闪屏之后的初始化工作全部完成后调用，例如：

  • 检查更新
  • 用户认证
  • 获取初始数据
  • 播放闪屏动画
app/_layout.tsx
import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';
import { ObserveRoot, useObserve } from 'expo-observe';
import { useEffect, useState } from 'react';

// 在获取资源期间保持闪屏可见
SplashScreen.preventAutoHideAsync();

function RootLayout() {
  const [isReady, setIsReady] = useState(false);
  const { markInteractive } = useObserve();

  useEffect(() => {
    async function prepare() {
      try {
        await authenticateUser();
        await fetchInitialData();
      } catch (e) {
        console.warn(e);
      } finally {
        setIsReady(true);
      }
    }

    prepare();
  }, []);

  useEffect(() => {
    if (isReady) {
      SplashScreen.hide();
      markInteractive();
    }
  }, [isReady, markInteractive]);

  if (!isReady) {
    return null;
  }

  return <Stack />;
}

export default ObserveRoot.wrap(RootLayout);

markInteractive() 可以在每个会话中安全地调用多次，但只有第一次调用会记录测量结果。如果你的应用有多个入口屏幕（例如引导流程、登录流程或深层链接目标），请在每一个此类屏幕上调用 markInteractive。如果你只在一个屏幕上放置它，那么当应用通过深层链接打开另一个屏幕时，就不会记录交互时间（TTI）。

4

创建新构建

在安装 expo-observe 并添加埋点后，请为你的应用创建一个新构建：

Terminal
- eas build

默认情况下，从调试构建收集的指标不会被发送。若要在调试构建中测试集成，请参阅在开发环境中启用指标。

5

查看你的指标

打开你的项目，并打开 EAS 控制台中的 Observe 选项卡 来查看来自你的应用的指标。

有关筛选、版本比较和会话调查的详细信息，请参阅 Dashboard 指南。

你也可以使用 EAS CLI 通过终端查询指标：

  • eas observe:versions：列出应用版本及其构建 ID、更新组 ID 和发布日期。可用于查找筛选其他命令所需的版本标识符。
  • eas observe:metrics-summary：显示按应用版本分组的聚合性能指标统计信息（例如中位数、p90 和 p99 值）。可用于比较不同发布版本的整体启动性能。
  • eas observe:metrics：显示按值排序的单个性能指标事件，包括会话和设备元数据。可用于调查特定的慢速会话或异常值。
  • eas observe:routes：显示按路由名称分组的导航指标（冷启动和热启动首次渲染时间，以及交互时间）。需要使用 Expo Router 或 React Navigation 集成。
  • eas observe:session：显示单个会话的完整事件时间线。
  • eas observe:events：显示你的应用通过 Observe.logEvent 发出的单个事件。详情请参阅用户定义的事件。

使用 --help 运行上述任一命令，即可查看可用的标志和参数。有关标志、指标名称和常见工作流，请参阅使用 EAS CLI 查询。

有关完整的库 API，包括配置选项和所有可用方法，请参阅 expo-observe API 参考。