dev-toolbar-review

Dev 工具栏评审指南

针对涉及 dev 工具栏（packages/dev-tools/）及其在 packages/common/ 中集成点的 PR 的评审清单。该工具栏会展示遥测事件，并且只允许在本地和 staging 环境中覆盖功能标志。

适用范围

修改以下任一路径的 PR 需要 growth eng 评审：

• packages/dev-tools/**（在 CODEOWNERS 中由 @supabase/growth-eng 负责）
• packages/common/posthog-client.ts（标志覆盖读取、事件订阅）
• packages/common/feature-flags.tsx（标志覆盖合并逻辑）
• 应用级挂载：apps/studio/、apps/www/、apps/docs/ 中的 DevToolbarProvider/DevToolbar/DevToolbarTrigger

注意：posthog-client.ts 和 feature-flags.tsx 不在 growth-eng 的 CODEOWNERS 中，因此只涉及这些文件的 PR 不会自动请求评审。请留意 PR 动态中的此类 PR。

评审清单

1. 环境保护

文件： packages/dev-tools/index.ts、DevToolbar.tsx、DevToolbarTrigger.tsx、DevToolbarContext.tsx

工具栏采用两层保护：

• 构建时 tree-shaking：在 index.ts 中，打包器会内联 process.env.NEXT_PUBLIC_ENVIRONMENT，因此 isToolbarEnabled = env === 'local' || env === 'staging' 会使导出三元表达式变为静态表达式。在这两个环境之外，所有导出都会变成存根（DevToolbar 和 DevToolbarTrigger 渲染 null，DevToolbarProvider 会原样传递子项，useDevToolbar 会返回一个空操作上下文），并且实现模块会从打包产物中移除。在 DevToolbarContext.tsx、DevToolbar.tsx、DevToolbarTrigger.tsx 和 feature-flags.tsx 中重复使用了同一条字面量 process.env 检查，因为打包器必须直接看到它——请确保这些检查保持一致。
• 实现中的运行时保护：IS_LOCAL_DEV = env === 'local' 会限制仅本地环境可用的功能——包括 DevToolbarContext.tsx 中的 SSE 事件流和 DevToolbar.tsx 中仅本地环境可用的 UI——因此 staging 环境可以使用工具栏，但不会启用这些功能。

请检查：

• 是否移除或放宽了保护条件。工具栏仅在 local 和 staging 环境中启用；preview 和 production 构建必须继续使用存根。
• index.ts 中的 tree-shaking 三元表达式是否保持不变——这是生产环境安全的主要保障。
• 是否有新增组件或导出绕过现有的保护模式。

2. 标志覆盖 Cookie

文件： packages/dev-tools/DevToolbar.tsx、packages/common/posthog-client.ts、packages/common/feature-flags.tsx

工具栏会写入两个用于在本地覆盖功能标志的 Cookie：

• x-ph-flag-overrides — PostHog 标志覆盖
• x-cc-flag-overrides — ConfigCat 标志覆盖

这些 Cookie 会由以下位置读取：

• posthog-client.ts:getFeatureFlag() — 在查询 SDK 之前检查 PostHog 覆盖 Cookie
• feature-flags.tsx — 初始化期间将这两个覆盖 Cookie 合并到标志存储中

请检查：

• Cookie 名称是否变更（写入方和所有读取方必须保持一致）
• feature-flags.tsx 中的合并／优先级逻辑是否变更（当前逻辑：先检查 vercel-flag-overrides，然后在本地开发环境中由 x-cc-flag-overrides 优先）
• 是否在 IS_LOCAL_DEV／isLocalDev 保护条件之外读取覆盖 Cookie——覆盖内容绝不能影响生产环境中的标志评估
• packages/dev-tools/utils.ts 中的 parseOverrideValue 或 valuesAreEqual 是否变更，以致可能引发类型强制转换错误

3. 遥测事件订阅

文件： packages/common/posthog-client.ts、packages/dev-tools/DevToolbarContext.tsx

工具栏通过 posthogClient.subscribeToEvents() 订阅客户端 PostHog 事件。 PostHog 客户端会在 capturePageView、capturePageLeave 和 identify 之后调用 emitToDevListeners()。注意：captureExperimentExposure 会直接调用 posthog.capture()， 不会向开发监听器发出事件——因此工具栏无法看到实验曝光事件。

检查以下内容：

• 对 emitToDevListeners 或 subscribeToEvents 的更改是否可能在实际采集路径中引入副作用（例如，抛出错误、阻塞或修改事件数据）
• 是否以同步方式遍历监听器集合（devListeners），从而延迟事件分发
• 新增的 PostHog 客户端方法是否采集事件却未调用 emitToDevListeners（导致工具栏可见性缺失）

4. SSE 服务遥测流

文件： packages/dev-tools/DevToolbarContext.tsx

工具栏通过服务器发送事件连接到 ${apiUrl}/telemetry/stream，以显示服务端遥测数据。 连接出错时会采用指数退避策略。

检查以下内容：

• SSE 端点 URL 或 session_id Cookie 处理是否有更改
• 重连逻辑的更改是否可能导致过度重试或连接泄漏
• 注意：流端点位于平台仓库中——跨仓库更改需要协调审查

5. 应用级挂载

Provider + 工具栏面板（DevToolbarProvider、DevToolbar）：

• apps/studio/pages/_app.tsx
• apps/www/pages/_app.tsx、apps/www/app/providers.tsx
• apps/docs/features/app.providers.tsx

触发按钮（DevToolbarTrigger）——在导航栏／页头组件中单独渲染：

• apps/studio/components/layouts/Navigation/LayoutHeader/LayoutHeader.tsx
• apps/www/components/Nav/index.tsx
• apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx

检查以下内容：

• 是否在某个应用中添加或移除了 Provider
• apiUrl 属性是否有更改（必须指向正确的平台 API）
• 渲染顺序的更改是否可能影响工具栏访问 PostHog 上下文

无需增长团队审核的更改

仅涉及工具栏面板内 UI/UX 的更改——样式、布局、文案、 拖动行为、弹出层定位——无需增长工程团队审核，除非同时涉及上述集成点。