api-flags-posthog-flags

使用 PostHog 实现功能标记

快速指南： 使用 PostHog 功能标记进行逐步发布、A/B 测试和远程配置。客户端：使用 useFeatureFlagEnabled hook。服务端：使用支持本地评估的 posthog-node。进行实验时，始终将 useFeatureFlagPayload 与 useFeatureFlagEnabled 搭配使用。每次检查标记时，都要处理 undefined 加载状态。

---

<critical_requirements>

重要：使用此技能前

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

（进行实验时，必须始终将 useFeatureFlagPayload 与 useFeatureFlagEnabled 或 useFeatureFlagVariantKey 搭配使用——payload hooks 不会发送曝光事件）

（服务端本地评估必须使用功能标记安全 API 密钥（phs_*）——个人 API 密钥已不再用于此用途）

（标记加载时，必须处理 undefined 状态——绝不能假设标记会立即可用）

（标记元数据中必须包含标记负责人和到期日期——缺少负责人会让标记成为无人维护的技术债）

（在多处使用标记时，必须将标记的使用封装在一个函数中——以免清理时留下无人维护的标记代码）

</critical_requirements>

---

自动检测： PostHog 功能标记、useFeatureFlagEnabled、useFeatureFlagPayload、useFeatureFlagVariantKey、PostHogFeature、isFeatureEnabled、getFeatureFlag、逐步发布、A/B 测试、实验、多变量标记

适用场景：

• 逐步发布（先发布给 10% 的用户，再到 50%，最后到 100%）
• 使用实验进行 A/B 测试（衡量变更的影响）
• 紧急开关（无需部署即可立即禁用功能）
• 远程配置（无需更改代码即可改变行为）
• Beta 功能自愿启用（让用户试用新功能）
• 用户定向（向特定群组展示功能）

不适用场景：

• 不会改变的简单开关（使用环境变量）
• 必须在编译时确定的配置（使用构建标记）
• 密钥或敏感数据（使用密钥管理）
• 始终应该启用的功能（直接发布代码即可）

涵盖的关键模式：

• 使用 React hooks 在客户端评估标记
• 使用本地评估实现高性能的服务端评估
• 布尔标记与多变量标记
• 使用百分比定向逐步发布
• A/B 测试与实验
• 用于远程配置的载荷
• 本地开发覆盖
• 标记清理与生命周期管理

---

详细资源：

• examples/core.md - 布尔标记、多变量标记、PostHogFeature 组件、载荷、实验、逐步发布、生命周期管理
• examples/server-side.md - 服务端评估、本地评估设置、分布式环境
• examples/development.md - 本地覆盖、引导、onFeatureFlags 回调
• reference.md - 决策框架与反模式

---

## 理念

功能标志将部署与发布解耦。你可以将代码部署到生产环境，同时控制谁能看到它，以及何时看到。这让你能够：

1. 安全发布 - 先向 1% 的用户推出，监控后再扩大范围
2. 快速回滚 - 无需部署即可立即关闭
3. 数据驱动的决策 - 通过 A/B 测试衡量影响
4. 渐进式交付 - 先面向 Beta 用户，再面向所有人

核心原则：

• 标志是临时的——从第一天起就规划好清理工作
• 标志要有负责人——每个标志都要有人负责
• 简单的标志更好——优先使用百分比逐步发布，而不是复杂的条件
• 处理未定义状态——标志会异步加载

何时使用功能标志：

• 需要逐步发布的高风险功能
• 需要通过 A/B 测试验证的功能
• 可能需要立即回滚的功能
• 用户可选择加入的 Beta 计划

何时不使用功能标志：

• 每个功能都使用（会增加维护负担）
• 永久性配置（使用配置文件）
• 已准备好面向 100% 用户发布的功能

---

核心模式

模式 1：客户端布尔标志

对于简单的开关功能，使用 useFeatureFlagEnabled。始终处理 undefined 加载状态——将其视为 false 会导致界面短暂显示错误内容。

const isNewCheckout = useFeatureFlagEnabled(FLAG_NEW_CHECKOUT);

if (isNewCheckout === undefined) return <Skeleton />;   // Loading
if (isNewCheckout) return <NewCheckout />;               // Enabled
return <LegacyCheckout />;                               // Disabled

在 lib/feature-flags.ts 中将标志键保存为命名常量，以避免拼写错误，并便于通过 grep 清理。

完整的正反示例请参阅 examples/core.md。

---

模式 2：多变量标志和变体

对于包含多个变体的 A/B 测试，使用 useFeatureFlagVariantKey。将变体常量与标志键一起定义。根据变体进行分支，并默认回退到 control。

const variant = useFeatureFlagVariantKey(FLAG_PRICING_PAGE);
if (variant === undefined) return <Skeleton />;

switch (variant) {
  case VARIANT_SIMPLE: return <SimplePricing />;
  case VARIANT_DETAILED: return <DetailedPricing />;
  default: return <ControlPricing />;
}

完整示例请参阅 examples/core.md。

---

模式 3：PostHogFeature 组件

PostHogFeature 组件可自动跟踪曝光，并内置回退处理，从而减少样板代码。布尔标志使用 match={true}，特定变体使用 match={VARIANT_KEY}。

<PostHogFeature flag={FLAG_BETA} match={true} fallback={<Legacy />}>
  <NewFeature />
</PostHogFeature>

布尔标志和变体示例请参阅 examples/core.md。

---

模式 4：用于远程配置的载荷

对于动态 JSON 配置，使用 useFeatureFlagPayload。始终与 useFeatureFlagEnabled 配对使用——仅使用载荷 Hook 不会发送曝光事件，从而破坏实验跟踪。

const isEnabled = useFeatureFlagEnabled(FLAG_BANNER); // Sends exposure event
const payload = useFeatureFlagPayload(FLAG_BANNER); // Gets config
const config = payload ?? DEFAULT_BANNER_CONFIG;

完整的正反示例请参阅 examples/core.md。

---

模式 5：服务端标志评估

使用 posthog-node 和 Feature Flags Secure API Key（phs_*）进行本地评估。这可将延迟从约 500ms（网络调用）降至约 10-50ms（本地评估）。尽管名称沿用旧版，personalApiKey 配置选项实际接受的是 phs_* 密钥。

export const posthog = new PostHog(process.env.POSTHOG_API_KEY!, {
  host: process.env.POSTHOG_HOST || "https://us.i.posthog.com",
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_KEY, // phs_* key
  featureFlagsPollingInterval: POSTHOG_POLL_INTERVAL_MS, // default 30s
});

API 处理器用法、仅本地评估以及分布式／无服务器环境的相关内容，请参阅 examples/server-side.md。

---

模式 6：标志生命周期与清理

每个标志都需要负责人、创建日期和预计移除日期。将标志检查封装在单个辅助函数中，这样清理时只需修改一个文件。

/**
 * Owner: @john-doe | Created: 2025-01-15 | Remove by: 2025-02-15
 */
export const FLAG_NEW_CHECKOUT = "new-checkout-flow";

export function isNewCheckoutEnabled(flag: boolean | undefined): boolean {
  return flag === true; // When removing: change to `return true;`
}

完整的文档模式和过期标志检测说明，请参阅 examples/core.md。

---

<red_flags>

危险信号

高优先级问题：

• 单独使用 useFeatureFlagPayload 进行实验（不会跟踪曝光）
• 在客户端暴露 Feature Flags Secure API 密钥（phs_*）（违反安全要求）
• 未处理加载状态（会导致 UI 闪烁）
• 功能标志没有负责人或到期日期（会变成永久技术债务）

中优先级问题：

• 使用魔法字符串作为功能标志键，而非常量（容易拼写错误，难以搜索）
• 在高流量功能标志上设置复杂的定向规则（影响性能）
• 在无外部缓存的无服务器/边缘环境中进行本地评估（导致冷启动问题）
• 未使用 PostHog 工具栏进行本地测试（调试更困难）

常见错误：

• 在多个位置检查功能标志，而不是使用包装函数
• SSR 时未预先加载功能标志（在 hydration 时出现内容闪烁）
• 运行实验时未定义主要指标
• 实验尚未完成就查看结果
• 将发布范围扩大到 100%，但没有清理计划

注意事项和边缘情况：

• PostHog 使用确定性哈希——同一用户始终会获得相同的变体
• 降低发布百分比可能会移除之前已纳入的用户
• 本地评估需要 Feature Flags Secure API Key（phs_*）——个人 API 密钥已弃用
• 功能标志会异步加载——首次渲染时始终为 undefined
• 在 posthog-node v3+ 中，GeoIP 定向默认使用服务器 IP
• 实验中每个变体至少需要 50 次曝光才能得出结果
• 过时的功能标志 = 发布范围为 100% 且 30 天内未评估
• onFeatureFlags 回调会接收三个参数：flags、flagVariants、{ errorsLoading }（第三个参数）
• 外部缓存提供程序（Redis、KV）仍处于实验阶段——仅适用于 Node.js/Python SDK

</red_flags>

---

<critical_reminders>

重要提醒

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

（进行实验时，必须始终将 useFeatureFlagPayload 与 useFeatureFlagEnabled 或 useFeatureFlagVariantKey 配对使用——payload hook 不会发送曝光事件）

（必须在服务端本地评估中使用功能标志安全 API 密钥（phs_*）——个人 API 密钥已弃用，不可用于此用途）

（必须处理功能标志加载时的 undefined 状态——绝不要假定功能标志会立即可用）

（必须在功能标志元数据中包含负责人和到期日期——没有负责人的功能标志会变成无人认领的技术债务）

（在多个位置使用功能标志时，必须将其用法封装在单个函数中——以免清理时遗留无人认领的功能标志代码）

不遵循这些规则会导致实验结果错误、安全漏洞、UI 闪烁和技术债务。

</critical_reminders>

---

来源

• PostHog React 集成
• PostHog 功能标志
• PostHog 功能标志最佳实践
• PostHog 服务端本地评估
• PostHog 创建功能标志
• PostHog 如何进行分阶段发布
• PostHog 功能标志测试
• PostHog 实验
• PostHog 功能标志覆盖
• 不要犯这些功能标志错误