当您需要一个可移植的、与框架无关的现场观察系统来监控任何 React 或 React Native 应用时，请使用此技能。它建立了一个类型化事件分类法（规范事件名称常量，绝不使用内联字符串），并提供最佳努力的非阻塞提供者分发，因此即使某个分析提供者失败或缺失，也绝不会...

目标：你可以回答“真实用户在做什么，他们正在经历什么？”—与一个

类型化事件词汇（没有到处都是字符串类型的 track("clicked_thing")）,

fan-out 是尽力而为的（一个故障的提供者永远不会破坏应用程序），真正的核心网页生命力指标

来自现场，并在任何操作之前尊重同意。

该系统是一个服务模块加上其常量（每个前端架构）。

src/
├── constants/
│   └── analytics.ts           ← canonical event names + AnalyticsEvent union
├── services/analytics/
│   ├── index.ts               ← barrel: track, adapters, types
│   ├── track.ts               ← the best-effort fan-out (single entry point)
│   ├── adapters.ts            ← one (event, props) => void per provider, window-guarded
│   ├── web-vitals.ts          ← report real-user LCP/INP/CLS into track()
│   └── consent.ts             ← consent gate read by the fan-out
├── providers/
│   └── AnalyticsProvider.tsx  ← 'use client' context exposing useAnalytics().track
└── error/
    └── ErrorBoundary.tsx      ← reports caught render errors via the fan-out

2. 事件分类法（有类型，绝不内联）

一个文件拥有每个事件名。组件引用常量；联合类型使拼写错误在编译时显现

错误和目录是唯一的真实来源。

// constants/analytics.ts
export const ANALYTICS_EVENTS = {
  PROJECT_CLICK: "project_click",
  GITHUB_CLICK: "github_click",
  RESUME_DOWNLOAD: "resume_download",
  CONTACT_SUBMISSION: "contact_submission",
} as const;

export type AnalyticsEvent =
  (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS];

// CORRECT — typed constant, autocompletes, can't typo
track(ANALYTICS_EVENTS.GITHUB_CLICK, { url });

// WRONG — stringly-typed, drifts, no compile check
track("github-click"); // ❌ silently a different event from "github_click"

track() 是唯一的入口点。它会遍历适配器注册表，对每一次调用进行保护，所以一个

提供者无法影响调用者或其他人。

// services/analytics/track.ts
import type { AnalyticsEvent } from "@/constants/analytics";
import { analyticsAdapters } from "./adapters";
import { hasConsent } from "./consent";

export function track(
  event: AnalyticsEvent,
  props?: Record<string, unknown>,
): void {
  if (!hasConsent()) return; // §6 — nothing fires before opt-in
  for (const adapter of analyticsAdapters) {
    try {
      adapter(event, props);
    } catch {
      /* best-effort: a failing/absent provider must never throw into the
         caller or block dispatch to the remaining providers. */
    }
  }
}

每个适配器都是一个微小的 (event, props) => void，它保护其提供者全局——在…时无操作

服务器（没有 window）以及当提供者脚本缺失时，所以是缺失或未加载的提供者

// services/analytics/adapters.ts
export type AnalyticsAdapter = (
  event: AnalyticsEvent,
  props?: Record<string, unknown>,
) => void;

export const googleAnalyticsAdapter: AnalyticsAdapter = (event, props) => {
  const w =
    typeof window !== "undefined" ? (window as AnalyticsGlobals) : undefined;
  if (!w || typeof w.gtag !== "function") return; // SSR-safe + absent-safe
  w.gtag("event", event, props ?? {});
};

export const clarityAdapter: AnalyticsAdapter = (event) => {
  const w =
    typeof window !== "undefined" ? (window as AnalyticsGlobals) : undefined;
  if (!w || typeof w.clarity !== "function") return;
  w.clarity("event", event);
};

// The registry track() fans out across. Exported + mutable so tests can swap
// in a recording sink to assert dispatch.
export const analyticsAdapters: AnalyticsAdapter[] = [
  googleAnalyticsAdapter,
  clarityAdapter,
  firebaseAdapter,
  // posthogAdapter, openPanelAdapter, …
];

3.1 Firebase 分析 — 一个适配器，两个平台

Firebase Analytics 提供两个 SDK，它们共享相同的 logEvent(name, params) 接口，所以一个

单个概念适配器同时覆盖网页和 React Native — 只需导入和“它是”

可用吗？守卫不同。在网页上，适配器从不在模块顶层导入 SDK（它是

仅限浏览器且异步，因此保持 SSR 安全。

// services/analytics/adapters.firebase.web.ts — Firebase JS SDK (web)
import type { Analytics } from "firebase/analytics";
import type { AnalyticsAdapter } from "./adapters";

// Held after a lazy, browser-only init (below) so the adapter stays synchronous + SSR-safe.
let analytics: Analytics | undefined;
export function setFirebaseAnalytics(instance: Analytics): void {
  analytics = instance;
}

export const firebaseAdapter: AnalyticsAdapter = (event, props) => {
  if (typeof window === "undefined" || !analytics) return; // SSR-safe + not-yet-ready safe
  void import("firebase/analytics").then(({ logEvent }) =>
    logEvent(analytics!, event, props),
  );
};

// services/analytics/firebase.init.ts — lazy, browser-only init (web)
import { initializeApp, getApps } from "firebase/app";
import { getAnalytics, isSupported } from "firebase/analytics";
import { setFirebaseAnalytics } from "./adapters.firebase.web";
import { FIREBASE_CONFIG } from "@/constants/analytics";

export async function initFirebaseAnalytics(): Promise<void> {
  if (typeof window === "undefined") return; // never on the server
  if (!(await isSupported())) return; // unsupported browser → no-op
  const app = getApps()[0] ?? initializeApp(FIREBASE_CONFIG);
  setFirebaseAnalytics(getAnalytics(app)); // adapter goes live after this
}

// services/analytics/adapters.firebase.native.ts — @react-native-firebase/analytics (RN / Expo)
import analytics from "@react-native-firebase/analytics";
import type { AnalyticsAdapter } from "./adapters";

export const firebaseAdapter: AnalyticsAdapter = (event, props) => {
  // RN: no window; the native module is present once the app boots.
  void analytics().logEvent(event, props);
};

相同形状，两个文件。 通过文件扩展名区分平台版本

（通过 Metro 的 .native.ts 解析的 adapters.firebase.native.ts，或通过 Platform.OS 切换）所以

注册表、track 分发、同意门、分类法和 useAnalytics 钩子从不改变

跨平台。Firebase 的事件名称规则（snake_case、小写、≤40 个字符）与

§2 中的分类规则，因此规范的 ANALYTICS_EVENTS 常量是有效的 Firebase 事件名称

按原样。在同意 (§6) 时启用 initFirebaseAnalytics() — Firebase 也会暴露

使用 setAnalyticsCollectionEnabled(false) 来加强选择退出功能。

为什么这个形状：分析是 _最后_ 一件应当导致应用崩溃的事情。一个供应商脚本会

无法加载，尚不存在的全局，一个在属性格式错误时抛出异常的适配器——都是

被包含的。注册表可以导出且可变，使得调度单元在不挂载任何东西的情况下可进行单元测试

在 'use client' 上下文中，可以通过 useAnalytics() 访问 track。在提供程序之外（测试时，

服务器）它返回一个无操作，因此被检测的组件在孤立状态下从不抛出异常。

// providers/AnalyticsProvider.tsx
"use client";
import { createContext, useContext, useMemo, type ReactNode } from "react";
import { track as trackEvent } from "@/services/analytics";
import type { AnalyticsEvent } from "@/constants/analytics";

interface AnalyticsContextValue {
  track: (event: AnalyticsEvent, props?: Record<string, unknown>) => void;
}
const AnalyticsContext = createContext<AnalyticsContextValue | null>(null);

export function AnalyticsProvider({ children }: { children: ReactNode }) {
  // track is module-level and stable → memoize once, never re-render consumers.
  const value = useMemo<AnalyticsContextValue>(
    () => ({ track: trackEvent }),
    [],
  );
  return (
    <AnalyticsContext.Provider value={value}>
      {children}
    </AnalyticsContext.Provider>
  );
}

const NOOP: AnalyticsContextValue = { track: () => undefined };
export function useAnalytics(): AnalyticsContextValue {
  return useContext(AnalyticsContext) ?? NOOP; // safe outside a provider / on server
}

// a tracked leaf — Server Components can't use the hook, so wrap in a thin client component
"use client";
export function TrackedGithubLink({ href, children }: Props) {
  const { track } = useAnalytics();
  return (
    <a
      href={href}
      onClick={() => track(ANALYTICS_EVENTS.GITHUB_CLICK, { url: href })}
    >
      {children}
    </a>
  );
}

提供者在渲染期间不进行任何工作——track 是稳定的，适配器自行保护

window 访问——因此在根目录挂载是安全的，包括在 SSR/RSC 树中。

5. 实际用户核心网页指标（实验室/现场循环）

通过相同的分发报告现场生命体征。这是灯塔技能的补充：

实验室门控设定预算；现场告诉你实际用户是否使用它。

// services/analytics/web-vitals.ts
import { onLCP, onINP, onCLS, onFCP, onTTFB, type Metric } from "web-vitals";
import { track } from "./track";

export function reportWebVitals(): void {
  const send = (m: Metric) =>
    track("web_vital" as AnalyticsEvent, {
      name: m.name, // LCP | INP | CLS | FCP | TTFB
      value: Math.round(m.name === "CLS" ? m.value * 1000 : m.value),
      rating: m.rating, // good | needs-improvement | poor
      id: m.id,
    });
  onLCP(send);
  onINP(send);
  onCLS(send);
  onFCP(send);
  onTTFB(send);
}

遥测仅在用户选择后触发，在分发边界检查一次 (§3) — 不会重复

// services/analytics/consent.ts
let granted = false; // hydrate from a stored consent cookie/localStorage on init
export function setConsent(value: boolean): void {
  granted = value;
}
export function hasConsent(): boolean {
  return granted;
}

捕获的渲染错误和未处理的拒绝通过相同的分发（或专用的 Sentry）

适配器），在刻意的边界处——而不是全局吞噬。

// error/ErrorBoundary.tsx (essence)
componentDidCatch(error: Error, info: ErrorInfo) {
  track("client_error" as AnalyticsEvent, {
    message: error.message, component: info.componentStack?.split("\n")[1]?.trim(),
  }); // or sentryAdapter(error, info)
}

分类扇出是恒定的；每个提供者都是一个窗口保护的适配器。

Firebase (web) logEvent(analytics, name, props) (firebase/analytics, lazy browser init)

Firebase (RN/Expo) analytics().logEvent(name, props) (@react-native-firebase/analytics)

Microsoft Clarity window.clarity("event", name)

PostHog window.posthog?.capture(name, props)

OpenPanel op("track", name, props) or op.track(name, props)

Sentry Sentry.captureException(error) (error adapter)

Next.js AnalyticsProvider in the root layout (client boundary); call initFirebaseAnalytics() in a client effect; vitals via useReportWebVitals.

React + Vite / Remix provider at app root; initFirebaseAnalytics() + reportWebVitals() in a top-level effect.

Expo / React Native swap the web-vitals source for RN performance APIs and the web provider scripts for native SDKs (@react-native-firebase/analytics, Amplitude, PostHog-RN); the taxonomy, track fan-out, consent gate, and useAnalytics hook are unchanged. The Firebase adapter is the same shape — it guards the native module instead of window (see §3.1).

9. 规范检查清单（在审查中执行）

Frontend Observability 实用指南

A portable, framework-agnostic field-side observability system for any React or React Native app. Establishes one typed event taxonomy (canonical event-name constants, never inline strings), a best-effort non-blocking provider fan-out so a failing or absent analytics provider can never...

人工智能

4核4G3M云服务器 新用户低至38元/年！

lighthouse

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

腾讯云开发者社区是腾讯云官方开发者社区，致力于打造开发者的技术分享型社区。提供专栏,问答，沙龙等产品和服务，汇聚海量精品云计算使用和开发经验，致力于帮助开发者快速成长与发展，营造开放的云计算技术生态圈。

Frontend Observability 实用指南

Frontend Observability 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐