设置 EAS 观察

学习如何安装 EAS Observe 并开始从你的生产应用收集性能指标。

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

🌐 EAS Observe tracks your app's startup performance in production. This guide walks you through installing the library, setting up your app, and viewing your first metrics.

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

先决条件

🌐 Prerequisites

先决条件

3 要求

Expo 用户账户

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

Expo SDK 55 或更高版本

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

一个EAS项目

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

安装库

🌐 Install the library

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

🌐 Make sure you are using the latest version of expo, then install expo-observe:

Terminal

- npx expo install --fix

- npx expo install expo-observe

封装你的根布局

🌐 Wrap your root layout

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

🌐 Wrap your root layout with AppMetricsRoot (SDK 55) or ObserveRoot (SDK 56 and later). This higher-order component (HOC) automatically measures Time to First Render (TTR) for you.

app/_layout.tsx

import { Stack } from 'expo-router';
import { ObserveRoot } from 'expo-observe';

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

export default ObserveRoot.wrap(RootLayout);

app/_layout.tsx

import { Stack } from 'expo-router';
import { AppMetricsRoot } from 'expo-observe';

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

export default AppMetricsRoot.wrap(RootLayout);

标记互动

🌐 Mark interactive

当你的应用完全准备好与用户交互时，请调用 markInteractive()。这应该在启动画面后面的任何初始化工作完成后调用，例如：

🌐 Call markInteractive() when your app is fully ready for user interaction. This should be called after any initialization work behind the splash screen completes, such as:

正在检查更新
正在验证用户身份
获取初始数据
动画启动画面

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';

// Keep the splash screen visible while we fetch resources
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);

app/_layout.tsx

import { Stack } from 'expo-router';
import * as SplashScreen from 'expo-splash-screen';
import { AppMetrics, AppMetricsRoot } from 'expo-observe';
import { useEffect, useState } from 'react';

// Keep the splash screen visible while we fetch resources
SplashScreen.preventAutoHideAsync();

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

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

    prepare();
  }, []);

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

  if (!isReady) {
    return null;
  }

  return <Stack />;
}

export default AppMetricsRoot.wrap(RootLayout);

信息 markInteractive() 可以在每个会话中安全地被调用多次，但只有第一次调用会记录测量值。如果你的应用有多个入口屏幕（例如，引导流程、登录流程或深度链接目标），请在每一个这些屏幕上调用 markInteractive。如果只在一个屏幕上调用，当应用通过指向不同屏幕的深度链接打开时，可交互时间 (TTI) 将不会被记录。

创建新版本

🌐 Create a new build

在安装 expo-observe 并添加了检测工具后，创建你的应用的新版本：

🌐 After installing expo-observe and adding the instrumentation, create a new build of your app:

Terminal

- eas build

信息默认情况下，从调试版本收集的指标不会被发送。要在调试版本中测试你的集成，请参见在开发中启用指标。

查看你的指标

🌐 View your metrics

打开你的项目，并在 EAS 仪表板中打开观察标签以查看你的应用指标。

🌐 Open your project and open Observe tab in EAS dashboard to view metrics from your app.

有关过滤、版本比较和会话调查的详细信息，请参阅仪表板指南。

🌐 For details on filtering, release comparison, and session investigation, see the Dashboard guide.

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

🌐 You can also query metrics from the terminal using the EAS CLI:

eas observe:versions：列出应用版本及其构建 ID、更新组 ID 和发布日期。对于查找筛选其他命令所需的版本标识符很有用。
eas observe:metrics-summary：显示按应用版本分组的汇总性能指标统计（例如中位数、p75 和 p95 值）。使用此功能比较各个版本的整体启动性能。
eas observe:metrics：显示按数值排序的各个性能指标事件，包括会话和设备元数据。使用此功能可调查特定的慢会话或异常值。
eas observe:events：显示你的应用通过 Observe.logEvent 发出的各个事件。详情请参阅用户自定义事件。

运行这些命令中的任何一个并加上 --help 以查看可用的标志和参数。

🌐 Run any of these commands with --help to see the available flags and arguments.