integration-nextjs-app-router

用途

本技能用于帮助开发者在 Next.js App Router 应用中添加 PostHog 分析集成。它提供了一套按顺序完成的集成工作流，并附带示例代码与参考文档，目标是让实现尽量贴合官方示例项目的模式。

工作流

集成需要按以下步骤依次完成：

1. basic-integration-1.0-begin.md — PostHog Setup - Begin（起点）
2. basic-integration-1.1-edit.md — PostHog Setup - Edit
3. basic-integration-1.2-revise.md — PostHog Setup - Revise
4. basic-integration-1.3-conclude.md — PostHog Setup - Conclusion

参考文件

• references/EXAMPLE.md — Next.js App Router 示例项目代码
• references/next-js.md — Next.js 文档
• references/identify-users.md — 识别用户文档
• references/basic-integration-1.0-begin.md — PostHog setup 开始
• references/basic-integration-1.1-edit.md — PostHog setup 编辑
• references/basic-integration-1.2-revise.md — PostHog setup 修订
• references/basic-integration-1.3-conclude.md — PostHog setup 收尾

示例项目展示了目标实现模式，API 细节请查阅文档。

核心原则

• 环境变量：PostHog 密钥必须使用环境变量，绝不硬编码。
• 最小改动：在现有集成旁添加 PostHog 代码，不替换或重构现有代码。
• 贴合示例：实现应尽量遵循示例项目的模式。

框架指引

• 对于 Next.js 15.3+，在 instrumentation-client.ts 中初始化 PostHog，这是最简单的设置方式。
• 对于特性开关，使用 useFeatureFlagEnabled() 或 useFeatureFlagPayload() 钩子，它们会自动处理加载状态和外部同步。
• 在用户操作发生的事件处理器中添加分析捕获，而不是在 useEffect 中响应状态变化。
• 不要用 useEffect 做数据转换，而是在渲染期间计算派生值。
• 不要用 useEffect 响应用户事件，把该逻辑放在事件处理器本身。
• 不要用 useEffect 链接状态更新，在事件处理器中一起计算所有相关更新。
• 不要用 useEffect 通知父组件，在事件处理器中与 setState 一起调用父回调。
• 当 prop 变化需要重置组件状态时，把 prop 作为组件的 key 传入，而不是使用 useEffect。
• useEffect 仅用于与外部系统同步（非 React 组件、浏览器 API、网络订阅）。

识别用户

在登录和注册事件中识别用户。请参考示例代码和文档，了解该框架正确的 identify 模式。如果前端和后端代码都存在，通过 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 头传递客户端会话和 distinct ID，以保持关联。

错误追踪

在相关文件中添加 PostHog 错误追踪，尤其是关键用户流程和 API 边界附近。

限制

资料未提供该技能支持的 Next.js 具体版本范围（除 15.3+ 初始化说明外）、PostHog 收费与价格、平台可用性、性能或效果数据，以及具体的安装命令或代码片段内容，这些暂未提供。