api-analytics-setup-posthog

PostHog 分析与功能标志设置

快速指南： 一次性设置 PostHog 分析和功能标志。涵盖 posthog-js 客户端提供程序、posthog-node 服务端客户端和环境变量。PostHog 同时提供分析和功能标志，免费额度十分慷慨（每月 100 万次事件 + 100 万次标志请求）。

---

<critical_requirements>

关键：使用此技能前

所有代码都必须遵循 CLAUDE.md 中的项目规范（kebab-case、命名导出、导入顺序、import type、命名常量）

（必须仅在客户端／浏览器环境中初始化 posthog-js——它依赖 window 和 localStorage 等浏览器 API）

（必须在服务端捕获事件后调用 posthog.shutdown()、posthog.flush()，或使用 captureImmediate()，以防事件丢失）

（必须使用 defaults: '2026-01-30'，以启用自动 SPA 页面跟踪和最新推荐行为）

</critical_requirements>

---

自动检测： PostHog 设置、posthog-js、posthog-node、PostHogProvider、分析设置、功能标志设置、事件跟踪设置、posthog.init

使用场景：

• 在项目中首次设置 PostHog
• 配置 PostHogProvider 以进行客户端分析
• 设置 posthog-node，以便在服务端／API 路由中捕获事件
• 配置 PostHog 环境变量

不适用场景：

• 设置完成后的事件跟踪模式（使用分析事件跟踪技能）
• 功能标志的使用模式（使用功能标志技能）
• 使用独立暂存／生产项目的复杂多环境设置

涵盖的关键模式：

• 使用 PostHogProvider 或框架初始化钩子进行客户端设置
• 使用 posthog-node 进行服务端设置
• 环境变量（客户端与服务端前缀）
• 用户识别与重置流程
• 无服务器刷新模式（captureImmediate 与 flush）

详细资源：

• examples/core.md - 提供程序设置、布局集成、用户识别、环境变量
• examples/server.md - 服务端客户端单例、API 路由、无服务器模式
• reference.md - 决策框架

---

理念

PostHog 是一个产品分析 + 功能标志平台，将多种工具整合为一。它是开源的，可自托管，并提供十分慷慨的免费额度。对于个人开发者和小型团队，PostHog 无需再使用独立的分析和功能标志服务。

核心原则：

1. 一个平台同时提供分析与功能标志 - 减少工具堆叠和成本
2. 按用量计费 - 按实际用量付费，而非按项目付费
3. 默认自动捕获 - 自动跟踪事件，减少手动埋点
4. 服务端和客户端 SDK - 全面支持 SSR 和客户端应用

适用场景：

• 需要在一个平台上同时使用分析和功能标志
• 希望获得慷慨的免费额度（每月 100 万次事件 + 100 万次标志请求）
• 倾向于使用开源方案，并希望支持自托管
• 构建产品分析功能（漏斗、留存、会话）

不适用场景：

• 需要具备严谨统计能力的高级 A/B 测试
• 需要实时事件流
• 已有成熟的分析与标志工具

---

核心模式

模式 1：PostHog 项目结构

为你的应用使用单个 PostHog 组织。一个组织可以汇总计费。每个应用使用独立项目，或者使用单个项目并通过自定义属性进行筛选。

PostHog Organization: "Your Company"
├── Project: "Main App" (or separate per app)
│   ├── API Key: phc_xxx
│   └── Host: https://us.i.posthog.com (or eu.i.posthog.com)

优点： 单个组织可汇总所有项目的计费；按用量计费；付费套餐包含 6 个项目

---

模式 2：客户端设置

安装 posthog-js，并配置 provider，或使用框架的客户端初始化钩子。

关键配置选项：defaults: "2026-01-30" 可启用推荐行为，person_profiles: "identified_only" 可降低成本。

有关这两种方式的完整实现，请参阅 examples/core.md。

优点： defaults 日期可启用自动 SPA 页面访问/离开跟踪，person_profiles: "identified_only" 可降低事件成本，开发环境中的调试模式有助于排查问题

---

模式 3：使用 posthog-node 进行服务端设置

安装 posthog-node，并创建单例以捕获服务端事件。

无服务器环境中的刷新选项：

• captureImmediate() - 最简单，直接等待 HTTP 请求（每个事件发送一个请求）
• capture() + await flush() - 批量处理，需要在响应返回前显式刷新

有关单例设置、API 路由用法和刷新反模式，请参阅 examples/server.md。

优点： 单例可避免创建多个客户端实例，flushInterval/flushAt 可配置批处理，captureImmediate 可简化无服务器环境中的用法

---

<red_flags>

注意事项

• 在服务端初始化 posthog-js（它需要浏览器 API，会导致崩溃）
• 在无服务器环境中进行服务端事件捕获后，没有调用 flush() 或 captureImmediate()（事件会悄然丢失）
• 客户端环境变量未暴露给浏览器 bundle（请检查框架的前缀约定）
• 在源代码中硬编码 API 密钥，而不是使用环境变量
• 用户退出登录时未调用 posthog.reset()（用户身份会泄漏到下一次会话）
• 未使用 defaults 日期选项（需要手动跟踪页面访问，会遗漏推荐行为）
• 身份验证后未调用 posthog.identify()（匿名会话和已验证身份的会话不会关联）
• 未设置 person_profiles: 'identified_only' 选项（会创建不必要的匿名用户档案，导致成本更高）
• 使用钩子时未用 PostHogProvider 包装应用（钩子会返回 null）
• 忘记在部署平台中添加环境变量（事件会悄然失败）
• 未意识到开发环境和生产环境使用了不同的 PostHog 项目（数据彼此独立）

注意事项与边缘情况：

• 必须在 window 可用后初始化 posthog-js（因此应使用 useEffect 或客户端初始化钩子）
• 服务端 SDK 不会像客户端那样自动刷新——必须显式调用 flush()、shutdown()，或使用 captureImmediate()
• captureImmediate() 更适合无服务器环境，但每个事件都会发送一个 HTTP 请求（不进行批处理）
• 免费套餐每月重置（达到 1M 个事件后，将停止捕获，直到下个月）
• person_profiles: 'identified_only' 可降低成本，但不会创建匿名用户档案
• 使用自动初始化钩子时，配置值在整个会话期间保持不变——只有在渲染前于服务端评估标记时，预置操作才会生效

</red_flags>

---

<critical_reminders>

重要提醒

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入顺序、import type、命名常量）

（必须仅在客户端/浏览器环境中初始化 posthog-js——它需要 window 和 localStorage 等浏览器 API）

（服务端事件捕获后，必须调用 posthog.shutdown()、posthog.flush()，或使用 captureImmediate()，以防事件丢失）

（必须使用 defaults: '2026-01-30'，以启用自动 SPA 页面跟踪和最新推荐行为）

不遵循这些规则会导致分析事件丢失、跟踪失效或安全漏洞。

</critical_reminders>

---

来源

• PostHog JavaScript SDK
• PostHog JavaScript 配置
• PostHog Node.js SDK