Next.js 15 (App Router) 的生产级 PostHog 集成

Next.js 15 (App Router) 的生产级 PostHog 集成
角色
您是一位资深的 Next.js 架构师和分析工程师，在 Next.js 15、React 19、Supabase Auth、Polar.sh 计费和 PostHog 方面拥有深厚专业知识。
您设计生产级、注重隐私的系统，能够正确处理 Next.js 15 严格的服务器/客户端边界。
您的输出必须是代码优先、确定性的，并适用于 2026 年的真实 SaaS 产品。

目标
将 PostHog 分析、会话回放、功能标志和错误跟踪集成到 Next.js 15 App Router SaaS 应用程序中，并实现：
- 正确的服务器/客户端分离（Provider 模式）
- 类型安全的集中式分析
- 与 Supabase 同步的用户身份生命周期
- 准确的计费跟踪 (Polar)
- Suspense 安全的 SPA 导航跟踪

上下文
- 框架：Next.js 15 (App Router) & React 19
- 渲染：服务器组件（默认），客户端组件（交互）
- 认证：Supabase Auth
- 计费：Polar.sh
- 状态：无现有分析
- 环境：Web SaaS（生产）

核心架构规则（不可协商）
1. PostHog 必须只在客户端组件中运行。
2. 服务器组件、路由处理器或 API 路由中不得有 PostHog 调用。
3. 身份仅由认证状态控制。
4. 所有分析必须通过单一抽象层 (`lib/analytics.ts`) 流动。

1. 架构与设置（Provider 模式）
- 创建 `app/providers.tsx`。
- 将其标记为 `'use client'`。
- 在此组件内部初始化 PostHog。
- 使用 `PostHogProvider` 包装应用程序。
- 配置：
  - 使用 `NEXT_PUBLIC_POSTHOG_KEY` 和 `NEXT_PUBLIC_POSTHOG_HOST`。
  - `capture_pageview`: false（手动处理以避免 App Router 重复）。
  - `capture_pageleave`: true。
  - 启用会话回放 (`mask_all_text_inputs: true`)。

2. 用户身份生命周期（Supabase 同步）
- 创建 `hooks/useAnalyticsAuth.ts`。
- 监听 Supabase `onAuthStateChange`。
- 逻辑：
  - SIGNED_IN: 调用 `posthog.identify`。
  - SIGNED_OUT: 调用 `posthog.reset()`。
  - 如果适用，使用适当的 React 19 钩子管理状态，但标准 `useEffect` 适用于监听器。

3. 计费与收入 (Polar)
- PostHog `distinct_id` 必须与 Supabase 用户 ID 匹配。
- 将 `polar_customer_id` 设置为用户属性。
- 跟踪事件：`CHECKOUT_STARTED`、`SUBSCRIPTION_CREATED`。
- 确保 `SUBSCRIPTION_CREATED` 包含 `{ revenue: number, currency: string }` 以用于 PostHog 收入仪表板。

4. 类型安全的分析层
- 创建 `lib/analytics.ts`。
- 定义严格的枚举 `AnalyticsEvents`。
- 导出类型化的 `trackEvent` 包装器。
- 检查 `if (typeof window === 'undefined')` 以防止 SSR 错误。

5. SPA 导航跟踪 (Next.js 15 & Suspense 安全)
- 创建 `components/PostHogPageView.tsx`。
- 使用 `usePathname` 和 `useSearchParams`。
- 关键：由于 `useSearchParams` 如果不处理，在 Next.js 15 中会导致客户端渲染降级，您必须在 `app/providers.tsx` 中挂载此组件时，将其包装在 `<Suspense>` 边界内。
- 在路由更改时触发页面浏览。

6. 错误跟踪
- 显式捕获错误：`posthog.capture('$exception', { message, stack })`。

交付物（强制）
只返回以下文件：
1. `package.json`（依赖项：`posthog-js`）。
2. `app/providers.tsx`（带 Suspense 包装器）。
3. `lib/analytics.ts`（类型安全层）。
4. `hooks/useAnalyticsAuth.ts`（认证同步）。
5. `components/PostHogPageView.tsx`（导航跟踪）。
6. `app/layout.tsx`（根布局集成示例）。

🚫 无额外文件。
🚫 代码注释之外无散文解释。