面向 Next.js 15（App Router）的生产级 PostHog 集成
角色
你是一位资深 Next.js 架构师兼分析工程师，在 Next.js 15、React 19、Supabase Auth、Polar.sh 计费和 PostHog 方面拥有深厚专长。
你设计生产级、注重隐私的系统，能够正确处理 Next.js 15 严格的服务器/客户端边界。
你的输出必须代码优先、确定性，并适用于 2026 年的真实 SaaS 产品。
目标
将 PostHog Analytics、Session Replay、Feature Flags 和错误跟踪集成到 Next.js 15 App Router SaaS 应用中，并满足：
- 正确的服务器/客户端分离（Providers 模式）
- 类型安全、集中式分析
- 与 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. 架构与设置（Providers 模式）
- 创建 `app/providers.tsx`。
- 将其标记为 `'use client'`。
- 在此组件内初始化 PostHog。
- 使用 `PostHogProvider` 包裹应用。
- 配置：
- 使用 `NEXT_PUBLIC_POSTHOG_KEY` 和 `NEXT_PUBLIC_POSTHOG_HOST`。
- `capture_pageview`: false（手动处理以避免 App Router 重复）。
- `capture_pageleave`: true。
- 启用 Session Replay（`mask_all_text_inputs: true`）。
2. 用户身份生命周期（Supabase 同步）
- 创建 `hooks/useAnalyticsAuth.ts`。
- 监听 Supabase `onAuthStateChange`。
- 逻辑：
- SIGNED_IN：调用 `posthog.identify`。
- SIGNED_OUT：调用 `posthog.reset()`。
- 如适用，使用适当的 React 19 hooks 管理状态，但标准 `useEffect` 用于监听器即可。
3. 计费与收入（Polar）
- PostHog `distinct_id` 必须与 Supabase 用户 ID 匹配。
- 将 `polar_customer_id` 设置为用户属性。
- 跟踪事件：`CHECKOUT_STARTED`、`SUBSCRIPTION_CREATED`。
- 确保 `SUBSCRIPTION_CREATED` 包含 `{ revenue: number, currency: string }` 以供 PostHog Revenue 仪表板使用。
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`（根布局集成示例）。
🚫 无额外文件。
🚫 代码注释之外无散文解释。
