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

安装和配置 PostHog 以进行产品分析、会话回放和错误跟踪的指南。

PostHog 是一个产品分析平台，提供会话回放、功能标志和错误跟踪。

EAS CLI 集成会自动完成标准的 PostHog React Native 设置：安装 SDK、创建 PostHog 组织和项目，以及配置你的环境变量。你也可以手动设置它，并且其余部分可保持本指南不变。

你将学到什么

本指南涵盖将 PostHog 集成到你的 Expo 项目中：

• 在 React Native 应用中安装并配置 PostHog
• 使用源映射和原生崩溃符号化进行错误跟踪
• 发布标记、标准 EAS 属性、功能标志和故障排查

安装并配置 PostHog

import { PostHogProvider } from 'posthog-react-native';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <PostHogProvider
      apiKey={process.env.EXPO_PUBLIC_POSTHOG_API_KEY}
      options={{
        host: process.env.EXPO_PUBLIC_POSTHOG_HOST,
        enableSessionReplay: false, // 如果你启用了 session replay，则设为 true
        // 捕获 JS 异常（如果你没有启用 error tracking，请移除）：
        errorTracking: {
          autocapture: { uncaughtExceptions: true, unhandledRejections: true },
        },
        // disabled: __DEV__, // 取消注释可停止从开发构建发送事件
      }}>
      <Slot />
    </PostHogProvider>
  );
}

import { Button } from 'react-native';
import { usePostHog } from 'posthog-react-native';

// 在组件内部
const posthog = usePostHog();
<Button title="发送测试事件" onPress={() => posthog?.capture('test_event')} />

错误追踪

如果你启用了错误追踪，PostHog 会对两种独立的内容进行符号化处理，并且它们需要分别配置：

• JavaScript 源映射：用于 JS/TS 异常，包括 Hermes 字节码。参见源映射。
• 原生调试符号：用于原生 Android 和 iOS 崩溃（ProGuard/R8 映射和 dSYM）。可选。参见原生崩溃符号化。

源映射

源映射会让 JavaScript 堆栈跟踪（包括 Hermes 字节码）指向你的原始源码，而不是压缩后的输出。

首先，设置注入，使每个 bundle 都带有上传标记。将以下内容添加到项目根目录中的 metro.config.js（如果文件不存在就创建一个）：

const { getPostHogExpoConfig } = require('posthog-react-native/metro');

const config = getPostHogExpoConfig(__dirname);

module.exports = config;

如果你已经自定义了 Metro 配置（例如使用 NativeWind 或在 monorepo 中），请对 getPostHogExpoConfig 返回的 config 对象进行修改，而不是自己调用 getDefaultConfig。

PostHog 的 CLI 使用 connect 设置的 POSTHOG_CLI_* 环境变量进行身份验证。如果要从你自己的机器上传，请改为运行 posthog-cli login。

在 EAS Build 中，posthog-react-native/expo 配置插件会在 Android（Gradle）和 iOS（Xcode）构建阶段自动上传源映射，因此无需额外运行命令。

在 EAS Update 中，空中更新只包含 JavaScript，因此每次更新后只需上传其源映射（原生符号在构建时固定）。安装 PostHog 的 CLI，然后每次导出一个平台并上传其映射：

dist 是 EAS Update 默认的输出目录。每次上传只导出一个平台：PostHog 会上传原生（Hermes）源映射，因此 dist 中的 Web bundle 不会被处理。

原生崩溃符号化

可选。原生崩溃（不同于 JavaScript 异常）需要在构建时上传原生调试符号。posthog-react-native/expo 插件在 EAS Build 中启用后即可执行此操作：

{
  "expo": {
    "plugins": [["posthog-react-native/expo", { "uploadNativeSymbols": true }]]
  }
}

这只是端到端所需的三个组成部分之一：构建时符号上传（上文）、在你的提供商中进行原生崩溃自动捕获，以及你在 PostHog 项目中的异常自动捕获设置。完整配置请参见 PostHog 的原生崩溃自动捕获。

发布标记

通过从 expo-updates 和 expo-constants 注册超级属性，将每个捕获的事件关联到生成它的更新、项目和账户：

import { useEffect } from 'react';
import Constants from 'expo-constants';
import * as Updates from 'expo-updates';
import { usePostHog } from 'posthog-react-native';

function ReleaseTagger() {
  const posthog = usePostHog();

  useEffect(() => {
    posthog?.register({
      'eas/update_id': Updates.updateId,
      'eas/channel': Updates.channel,
      'eas/runtime_version': Updates.runtimeVersion,
      'eas/project_id': Constants.expoConfig?.extra?.eas?.projectId,
      'eas/account': Constants.expoConfig?.owner,
    });
  }, [posthog]);

  return null;
}

在 <PostHogProvider> 中渲染 <ReleaseTagger />。之后的每次 capture() 都会携带这些属性，因此你可以在 PostHog 中按 eas/update_id 筛选或分组事件。只有当你的应用配置设置了 owner 时，eas/account 才有值。eas/update_id 和 eas/channel 仅在 release 和 preview 构建中设置。在 Expo Go 和开发构建中，它们的值为 null，因此这些构建产生的事件不会携带它们。

标准 EAS 属性

PostHog 可以识别这些 eas/ 名称。它会在每个名称旁显示 Expo 徽标，并将带有标识符的属性链接到 expo.dev 上对应的页面。每个值的来源取决于事件是在你的应用中触发，还是在工作流中触发：

ReleaseTagger 代码片段会从 expo-updates 和 expo-constants 设置应用内的值。在工作流中，通过 eas/posthog_capture_event 设置相同的名称：eas/account、eas/project_id 和 eas/workflow_id 分别来自 account、app 和 workflow 上下文，每个作业都可以读取这些上下文。构建和更新字段来自构建或更新作业的输出。配方展示了具体用法。eas/update_id 在应用中是单个更新 ID，在工作流中则是更新组 ID；一次发布会生成一组特定于平台的更新。两者都会在 expo.dev 上打开对应更新。

功能标志

一旦提供程序设置完成，功能标志即可工作，无需额外配置。请参阅 PostHog 的 React Native 功能标志 和引导加载，以避免应用启动时进行一次网络往返。

与 EAS Workflows 一起使用

EAS Workflows 可以从 CI 流程中与 PostHog 进行交互。你可以发送事件、创建注释、推出功能标志、根据实时指标控制发布流程，以及将源映射作为工作流步骤上传。这些步骤会自动读取 connect 设置的 EXPO_PUBLIC_POSTHOG_* 和 POSTHOG_CLI_* 环境变量。有关每个步骤的完整输入参考，请参阅 EAS Workflows 语法参考中的 PostHog 函数。

管理集成

之后可使用以下命令来管理该集成：

dashboard 会打开你关联的 PostHog 项目。disconnect 仅会移除 Expo 端的关联。你的 PostHog 组织、项目和数据都会保留不变。

手动设置

connect 是标准 PostHog React Native 设置的快捷方式。要手动进行设置，请遵循 PostHog 的 React Native 安装指南，然后设置 EXPO_PUBLIC_POSTHOG_API_KEY 和 EXPO_PUBLIC_POSTHOG_HOST（以及用于源映射的 POSTHOG_CLI_* 变量）。按照步骤 2 所示，将你的应用包裹在 <PostHogProvider> 中。关于源映射，请参见源映射。

故障排查

了解更多

• PostHog React Native 库
• React Native 的产品分析
• React Native 的错误追踪
• React Native 的会话回放
• 为 React Native 上传源映射
• React Native 的功能开关