posthog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/posthog

World-class PostHog integration. Audit, fix, verify—every time.

业界领先的PostHog集成方案。审计、修复、验证——每次运行全流程覆盖。

What This Does

功能说明

Examines your PostHog integration, identifies every gap, implements fixes, and verifies event tracking works end-to-end. No partial modes. Every run does the full cycle.

检查你的PostHog集成情况，识别所有漏洞，实施修复，并端到端验证事件追踪功能是否正常运行。无部分模式，每次运行都会执行完整周期。

Branching

分支管理

Assumes you start on

master

main

. Before making code changes:

bash

git checkout -b fix/posthog-$(date +%Y%m%d)

Configuration-only changes (env vars, dashboard settings) don't require a branch. Code changes do.

假设你从

master

main

分支开始。在修改代码前：

bash

git checkout -b fix/posthog-$(date +%Y%m%d)

仅配置变更（环境变量、仪表盘设置）无需创建分支，代码变更则需要。

Process

流程

0. Environment Check

0. 环境检查

Verify PostHog is reachable and configured:

bash

~/.claude/skills/posthog/scripts/detect-environment.sh

This checks:

```
NEXT_PUBLIC_POSTHOG_KEY
```
is set
```
NEXT_PUBLIC_POSTHOG_HOST
```
is set (or defaults correctly)
PostHog API is reachable
MCP connection is active

验证PostHog是否可访问且配置正确：

bash

~/.claude/skills/posthog/scripts/detect-environment.sh

该脚本检查以下内容：

是否已设置
```
NEXT_PUBLIC_POSTHOG_KEY
```
是否已设置
```
NEXT_PUBLIC_POSTHOG_HOST
```
（或已正确使用默认值）
PostHog API是否可访问
MCP连接是否活跃

1. Audit

1. 审计

Spawn the auditor. Use the

posthog-auditor

subagent for deep parallel analysis. It examines:

Configuration — Env vars on all deployments, cross-platform parity
SDK Setup — Initialization, provider placement, privacy settings
Event Quality — Events defined, consistent naming, not too noisy
Privacy Compliance — PII masking, consent handling, GDPR readiness
Feature Flags — Active flags, stale flags, evaluation patterns
Integration Health — Events flowing, no ingestion warnings

Use MCP tools for live data:

mcp__posthog__event-definitions-list — See what events are tracked
mcp__posthog__feature-flag-get-all — Audit active feature flags
mcp__posthog__list-errors — Check for error tracking issues
mcp__posthog__logs-query — Search for SDK/ingestion errors

Research first. Before assuming current patterns are correct, check PostHog docs:

mcp__posthog__docs-search query="[topic]"

启动审计工具。 使用

posthog-auditor

子代理进行深度并行分析，检查范围包括：

配置 — 所有部署环境的环境变量、跨平台一致性
SDK设置 — 初始化、提供者部署、隐私设置
事件质量 — 已定义事件、命名一致性、无过度冗余
隐私合规 — PII掩码、同意管理、GDPR合规性
功能标志 — 活跃标志、过期标志、评估模式
集成健康度 — 事件流转、无摄入警告

使用MCP工具获取实时数据：

mcp__posthog__event-definitions-list — 查看已追踪的事件
mcp__posthog__feature-flag-get-all — 审计活跃功能标志
mcp__posthog__list-errors — 检查错误追踪问题
mcp__posthog__logs-query — 搜索SDK/摄入错误

先调研。 在假设当前模式正确之前，请查阅PostHog文档：

mcp__posthog__docs-search query="[主题]"

2. Plan

2. 规划

From audit findings, build a complete remediation plan:

Finding Type	Action
Missing env vars	Fix directly with Vercel/Convex CLI
SDK misconfiguration	Delegate to Codex with clear specs
Missing events	Define event schema, implement tracking
Privacy gaps	Apply `references/privacy-checklist.md`
Feature flag cleanup	Archive stale flags via MCP

Prioritize:

Critical — Events not sending, SDK not initialized
High — Privacy issues, PII leakage, missing masking
Medium — Suboptimal patterns, missing events
Low — Cleanup, organization, dashboards

基于审计结果，制定完整的修复计划：

问题类型	操作
缺失环境变量	使用Vercel/Convex CLI直接修复
SDK配置错误	委托给Codex并提供明确规范
缺失事件	定义事件架构，实现追踪功能
隐私漏洞	应用 `references/privacy-checklist.md`
功能标志清理	通过MCP归档过期标志

优先级排序：

关键 — 事件无法发送、SDK未初始化
高 — 隐私问题、PII泄露、缺失掩码
中 — 模式优化不足、缺失事件
低 — 清理、整理、仪表盘优化

3. Execute

3. 执行

Fix everything. Don't stop at a report.

Configuration fixes (do directly):

bash

undefined

修复所有问题。 不要仅停留在报告阶段。

配置修复（直接执行）：

bash

undefined

Missing env var on Vercel

Vercel上缺失环境变量

printf '%s' 'phc_xxx' | vercel env add NEXT_PUBLIC_POSTHOG_KEY production

Missing env var on Convex (for server-side tracking)

Convex上缺失环境变量（用于服务端追踪）

npx convex env set --prod POSTHOG_API_KEY "phc_xxx"


**SDK setup fixes (delegate to Codex):**
```bash
codex exec --full-auto "Fix PostHog initialization. \
File: lib/analytics/posthog.ts. \
Problem: [what's wrong]. \
Solution: [what it should do]. \
Reference: ~/.claude/skills/posthog/references/sdk-patterns.md. \
Verify: pnpm typecheck && pnpm test" \
--output-last-message /tmp/codex-fix.md 2>/dev/null

Event schema updates: Use

mcp__posthog__action-create

to define composite events.

Feature flag cleanup: Use

mcp__posthog__delete-feature-flag

to remove stale flags.

npx convex env set --prod POSTHOG_API_KEY "phc_xxx"


**SDK设置修复（委托给Codex）：**
```bash
codex exec --full-auto "Fix PostHog initialization. \
File: lib/analytics/posthog.ts. \
Problem: [问题描述]. \
Solution: [解决方案]. \
Reference: ~/.claude/skills/posthog/references/sdk-patterns.md. \
Verify: pnpm typecheck && pnpm test" \
--output-last-message /tmp/codex-fix.md 2>/dev/null

事件架构更新： 使用

mcp__posthog__action-create

定义复合事件。

功能标志清理： 使用

mcp__posthog__delete-feature-flag

移除过期标志。

4. Verify

4. 验证

Prove it works. Not "looks right"—actually works.

Configuration verification:

bash

undefined

证明功能正常。 不是“看起来正确”，而是实际可用。

配置验证：

bash

undefined

Check env vars exist

检查环境变量是否存在

vercel env ls --environment=production | grep POSTHOG npx convex env list --prod | grep POSTHOG


**Event flow verification using MCP:**

vercel env ls --environment=production | grep POSTHOG npx convex env list --prod | grep POSTHOG


**使用MCP验证事件流转：**

Check recent events are flowing

检查近期事件是否正常流转

mcp__posthog__query-run with TrendsQuery for last 24h

Check for ingestion warnings

检查摄入警告

mcp__posthog__list-errors

Verify event definitions exist

验证事件定义是否存在

mcp__posthog__event-definitions-list


**SDK initialization verification:**
1. Open browser DevTools → Network tab
2. Filter for `posthog` or `i.posthog.com`
3. Trigger an action → verify event sent
4. Check PostHog Live Events → verify event received

**Privacy verification:**
1. Session Replay shows masked inputs (`***`)
2. Person profiles show only user ID, not email/name
3. Autocapture text is masked

If any verification fails, go back and fix it.

mcp__posthog__event-definitions-list


**SDK初始化验证：**
1. 打开浏览器开发者工具 → 网络标签
2. 筛选`posthog`或`i.posthog.com`
3. 触发操作 → 验证事件已发送
4. 查看PostHog实时事件 → 验证事件已接收

**隐私验证：**
1. 会话回放显示输入内容已掩码（`***`）
2. 用户档案仅显示用户ID，不包含邮箱/姓名
3. 自动捕获的文本已掩码

如果任何验证步骤失败，请返回修复。

Common Issues & Fixes

常见问题与修复

Events Not Sending

事件无法发送

Symptoms: No events in PostHog, network requests failing

Debug steps:

Check if PostHog initialized:
```
posthog.__loaded
```
in console
Check network tab for blocked requests (ad blockers)
Enable debug mode:
```
posthog.debug()
```
in console
Test with webhook.site to isolate SDK vs network issues

Fixes:

Set up reverse proxy (
```
/ingest
```
→ PostHog) to bypass ad blockers
Ensure
```
initPostHog()
```
called in provider
Check
```
NEXT_PUBLIC_POSTHOG_KEY
```
is actually public (has
```
NEXT_PUBLIC_
```
prefix)

症状： PostHog中无事件、网络请求失败

调试步骤：

检查PostHog是否初始化：在控制台输入
```
posthog.__loaded
```
在网络标签检查是否有请求被拦截（广告拦截器）
启用调试模式：在控制台输入
```
posthog.debug()
```
使用webhook.site测试以隔离SDK或网络问题

修复方案：

设置反向代理（
```
/ingest
```
→ PostHog）以绕过广告拦截器
确保在提供者中调用
```
initPostHog()
```
检查
```
NEXT_PUBLIC_POSTHOG_KEY
```
是否为公开变量（带有
```
NEXT_PUBLIC_
```
前缀）

Bot Detection Blocking Dev Events

机器人检测阻止开发环境事件

Symptoms: Events work in production but not local dev

Cause: Chrome launched from debugger triggers bot detection

Fix:

typescript

posthog.init(key, {
  opt_out_capturing_by_default: false,
  // For development only:
  bootstrap: { isIdentifiedAnonymous: true },
});

症状： 生产环境事件正常，但本地开发环境无事件

原因： 从调试器启动的Chrome触发了机器人检测

修复方案：

typescript

posthog.init(key, {
  opt_out_capturing_by_default: false,
  // 仅用于开发环境:
  bootstrap: { isIdentifiedAnonymous: true },
});

Identify Called Before Init

Identify在Init之前调用

Symptoms: User not linked to events, anonymous users everywhere

Fix:

typescript

// WRONG
posthog.identify(userId); // Called before init completes

// RIGHT
posthog.init(key, {
  loaded: (ph) => {
    if (userId) ph.identify(userId);
  },
});

症状： 用户未与事件关联，所有用户均显示为匿名

修复方案：

typescript

// 错误写法
posthog.identify(userId); // 在初始化完成前调用

// 正确写法
posthog.init(key, {
  loaded: (ph) => {
    if (userId) ph.identify(userId);
  },
});

Missing Reverse Proxy

缺失反向代理

Symptoms: Events blocked by ad blockers in production

Fix (Next.js):

typescript

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/ingest/:path*',
        destination: 'https://us.i.posthog.com/:path*',
      },
    ];
  },
};

Then update init:

typescript

posthog.init(key, {
  api_host: '/ingest',
});

症状： 生产环境中事件被广告拦截器阻止

修复方案（Next.js）：

typescript

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/ingest/:path*',
        destination: 'https://us.i.posthog.com/:path*',
      },
    ];
  },
};

然后更新初始化代码：

typescript

posthog.init(key, {
  api_host: '/ingest',
});

MCP Tool Reference

MCP工具参考

Tool	Purpose
`mcp__posthog__event-definitions-list`	List all tracked events
`mcp__posthog__query-run`	Run trends/funnels queries
`mcp__posthog__feature-flag-get-all`	List feature flags
`mcp__posthog__create-feature-flag`	Create new flag
`mcp__posthog__list-errors`	Check error tracking
`mcp__posthog__logs-query`	Search logs for issues
`mcp__posthog__docs-search`	Search PostHog docs
`mcp__posthog__entity-search`	Find insights/dashboards/flags
`mcp__posthog__projects-get`	List available projects
`mcp__posthog__switch-project`	Change active project

工具	用途
`mcp__posthog__event-definitions-list`	查看所有已追踪事件
`mcp__posthog__query-run`	运行趋势/漏斗查询
`mcp__posthog__feature-flag-get-all`	查看功能标志
`mcp__posthog__create-feature-flag`	创建新标志
`mcp__posthog__list-errors`	检查错误追踪
`mcp__posthog__logs-query`	搜索日志排查问题
`mcp__posthog__docs-search`	搜索PostHog文档
`mcp__posthog__entity-search`	查找洞察/仪表盘/标志
`mcp__posthog__projects-get`	查看可用项目
`mcp__posthog__switch-project`	切换活跃项目

Default Stack

默认技术栈

Assumes Next.js + TypeScript + Convex + Vercel + Clerk. Adapts gracefully to other stacks.

假设使用Next.js + TypeScript + Convex + Vercel + Clerk，也可适配其他技术栈。

What You Get

最终成果

When complete:

Working event tracking (events visible in PostHog Live Events)
Proper SDK initialization with privacy settings
Reverse proxy configured for ad blocker bypass
User identification linked to auth (Clerk/etc)
Feature flags ready to use
Standard events defined and tracking
All configuration in place (dev and prod)
Deep verification passing

完成后将获得：

正常工作的事件追踪（事件可在PostHog实时事件中查看）
带有隐私设置的正确SDK初始化
已配置反向代理以绕过广告拦截器
用户身份验证与事件关联（Clerk等）
可直接使用的功能标志
已定义并追踪的标准事件
所有环境（开发与生产）配置完成
深度验证全部通过

posthog

Original

Translation

/posthog

/posthog

What This Does

功能说明

Branching

分支管理

Process

流程

0. Environment Check

0. 环境检查

1. Audit

1. 审计

2. Plan

2. 规划

3. Execute

3. 执行

Missing env var on Vercel

Vercel上缺失环境变量

Missing env var on Convex (for server-side tracking)

Convex上缺失环境变量（用于服务端追踪）

4. Verify

4. 验证

Check env vars exist

检查环境变量是否存在

Check recent events are flowing

检查近期事件是否正常流转

Check for ingestion warnings

检查摄入警告

Verify event definitions exist

验证事件定义是否存在

Common Issues & Fixes

常见问题与修复

Events Not Sending

事件无法发送

Bot Detection Blocking Dev Events

机器人检测阻止开发环境事件

Identify Called Before Init

Identify在Init之前调用

Missing Reverse Proxy

缺失反向代理

MCP Tool Reference

MCP工具参考

Default Stack

默认技术栈

What You Get

最终成果

Sources

参考来源