feature-flags-nextjs

Next.js 的 PostHog 功能标志

此技能可帮助你在 Next.js 应用中添加 PostHog 功能标志。

参考文件

• references/react.md - React 功能标志安装 - 文档
• references/next-js.md - Next.js - 文档
• references/adding-feature-flag-code.md - 添加功能标志代码 - 文档
• references/best-practices.md - 功能标志最佳实践 - 文档

请参阅文档，了解 API 详情和框架特定模式。

关键原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
• 最小改动：在现有逻辑旁添加功能标志代码。不要替换或重构现有代码。
• 优先使用布尔标志：除非用户明确要求使用多变量标志，否则默认进行布尔标志检查。
• 尽可能在服务端执行：优先在服务端评估标志，以避免 UI 闪烁。

PostHog MCP 工具

检查是否已连接 PostHog MCP 服务。如果可用，请查找与功能标志管理相关的工具（创建、列出、更新和删除标志）。使用这些工具直接在 PostHog 中管理标志，而不是要求用户在仪表板中手动操作。

框架指南

• 对于 Next.js 15.3 及更高版本，最简单的设置方式是在 instrumentation-client.ts 中初始化 PostHog
• 如果 posthog-js 已初始化（例如通过 instrumentation-client.ts），PostHog React 钩子（useFeatureFlagEnabled、useFeatureFlagPayload）无需 PostHogProvider 即可使用
• 在客户端组件中，直接导入并使用钩子——React 上下文默认使用 posthog-js 单例
• 不要仅为功能标志将组件包裹在 PostHogProvider 中——如果 posthog-js 已在全局初始化，就没有必要
• 服务端组件和路由处理程序不能使用 React 钩子——请改用 posthog-node SDK
• 使用 posthog-node 创建服务端 PostHog 客户端，调用 getAllFlags() 或 getFeatureFlag()，然后等待 posthog.shutdown()
• 将标志值作为属性从服务端传递给客户端组件，以避免水合不匹配
• 对于会影响初始渲染的标志，请在服务端进行评估并作为属性传递，以避免 UI 闪烁
• 客户端钩子在标志加载期间可能会先返回 undefined——请处理此加载状态
• 对于功能标志，请使用 useFeatureFlagEnabled() 或 useFeatureFlagPayload() 钩子——它们会自动处理加载状态和外部同步
• 在用户操作发生的事件处理程序中添加分析事件采集，不要在响应状态变化的 useEffect 中添加
• 不要将 useEffect 用于数据转换——应在渲染期间计算派生值
• 不要使用 useEffect 响应用户事件——应将逻辑放在事件处理程序本身中
• 不要使用 useEffect 串联状态更新——应在事件处理程序中一起计算所有相关更新
• 不要使用 useEffect 通知父组件——应在事件处理程序中调用 setState 的同时调用父组件回调
• 若要在属性变化时重置组件状态，请将该属性作为组件的 key 传入，而不是使用 useEffect
• useEffect 仅用于与外部系统同步（非 React 控件、浏览器 API、网络订阅）