设置 Expo 观察

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

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

🌐 Expo 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.

先决条件

🌐 Prerequisites

Prerequisites

4 requirements

访问 Expo Observe 预览

Expo Observe 处于私有预览阶段，可根据请求授予访问权限。在此请求访问。

Expo 用户账户

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

Expo SDK 55 或更高版本

Expo 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 封装你的根布局。这个高阶组件（HOC）会自动为你测量首次渲染时间（TTR）。

🌐 Wrap your root layout with AppMetricsRoot. This higher-order component (HOC) automatically measures Time to First Render (TTR) for you.

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 { 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);

App.tsx

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

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

function App() {
  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.hideAsync();
      AppMetrics.markInteractive();
    }
  }, [isReady]);

  if (!isReady) {
    return null;
  }

  // your app
}

export default AppMetricsRoot.wrap(App);

信息 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：显示按应用版本分组的聚合性能指标（例如中位数、p75 和 p95 值）。使用此信息比较不同版本的整体启动性能。
eas observe:events：显示按指标值排序的各个性能事件，包括会话和设备元数据。使用此功能可调查特定的慢速会话或异常值。

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

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