上线一个月，你却回答不出三个问题：vibe 项目的埋点与数据分析实战

AI 给你写了功能，但没给你装眼睛

上个月我跟一个朋友聊天。他用 Claude 搭了一个 PDF 转 Markdown 的工具，从第一行提示词到上线收款只花了四天。上线一个月后我问他：每天多少人来？他们从哪儿来？多少人注册后一次核心功能都没用就走了？

他沉默了很久，说后台只有一条 Vercel 的访问曲线和 Stripe 的三笔订单。多少人来过、从哪儿来、在哪一步流失——一个都答不上来。功能是 AI 写的，眼睛却没装上。

这就是绝大多数 vibe coding 项目的现状：prompt 写得飞快，上线按钮按得果断，然后在"好像有人用、又好像没人用"的薛定谔状态里过了一个月。埋点这件事，听起来像大公司的奢侈品，实际上恰恰是一人项目最划算的投资——因为你没有产品经理帮你看数据，你就是产品经理；你没有增长团队帮你做实验，你就是增长团队。没有数据，你连"该改什么"都只能靠猜。

这篇指南不讲高深的数据科学，只讲一个独立开发者在三天内能落地、之后每周花一小时就能用的完整方案：选什么工具、事件怎么设计、代码怎么写、隐私怎么合规、以及怎么把数据变成行动。

工具怎么选：PostHog、Umami、Plausible 三选一

市面上的分析工具很多，但一人团队的选型逻辑跟大公司完全不同。大公司关心的是权限体系和 BI 集成；你关心的是三件事：免费额度够不够、部署和维护麻不麻烦、能不能做漏斗和留存这种真正有用的分析，而不是只看 PV 曲线。

先把结论放在前面：绝大多数 vibe 项目直接选 PostHog Cloud 就行。它有慷慨的免费额度，事件、漏斗、留存、A/B 测试全套都有，SDK 一行代码初始化。下面这张表是给"就是想自己掌控一切"或者"隐私要求极端"的人看的。

维度	PostHog	Umami	Plausible
定位	全功能产品分析（事件+漏斗+留存+实验）	轻量访问统计，Google Analytics 的极简替代	轻量隐私友好统计，无 cookie
部署	Cloud 开箱即用；也支持 Docker 自托管	必须自托管（Node + 数据库）	Cloud 开箱即用；也支持自托管
免费/成本	Cloud 有免费额度，一人项目通常够用，以官方定价为准	软件本身免费，成本是你的服务器和维护时间	Cloud 按月付费；自托管免费但自己运维
隐私	可选欧盟数据中心，支持关闭 cookie、提供 opt-out API	数据完全在自己服务器，无第三方	默认无 cookie，GDPR 友好是其卖点
漏斗/留存	原生支持，这是它最大的优势	不支持，只能看页面访问
维护成本	Cloud 版零维护；自托管版需要你管数据库和升级	你要自己管备份、升级、可用性	Cloud 版零维护

怎么选，一句话：如果你的项目有注册、有核心功能、有付费——也就是你需要回答"用户在哪一步流失"——选 PostHog。如果只是一个静态展示页、你只想知道每天多少人看、从哪儿来，Umami 自托管或者 Plausible Cloud 更轻、更快。我的建议是：别为了省几十块钱的订阅费，去花每周两小时运维一个统计服务。一人团队最贵的是你的时间。

关于自托管多说一句。很多独立开发者有种执念：数据必须在自己手里。这执念本身没错，但要算清楚账：PostHog 自托管需要跑 Postgres、ClickHouse、Redis 整套栈（具体以官方文档为准），升级和备份都是你的活。除非你的用户明确要求数据不出境，或者你在做合规敏感的行业，否则 Cloud 版加欧盟数据中心已经足够。把省下来的时间拿去改转化率，回报率高得多。

事件设计：先定命名规范，再谈埋点

工具装好了，第二个坑是事件命名。我见过太多项目的事件列表长这样：click1、test_event、按钮点击_最终版。三个月后连作者自己都看不懂，数据直接作废。事件设计只有一条铁律：命名规范先行，而且一旦定下来就不改——改名意味着历史数据断裂。

推荐用 动词_对象 的 snake_case 格式，全部小写英文：

• signup_completed —— 注册完成（不是 signup，完成态才有意义）
• project_created —— 用户创建了第一个项目/文档/任务
• core_action_completed —— 完成了产品的核心动作（生成、导出、发布……按你的产品定义）
• paywall_viewed —— 看到了付费墙
• checkout_started —— 进入支付流程
• payment_succeeded —— 支付成功

命名之外，每个事件要带上关键属性（properties）。比如 payment_succeeded 带上 plan（套餐名）和 amount（金额）；core_action_completed 带上 action_type。属性是事后分析的弹药，埋的时候多带一点不吃亏，少了可补不回来。

一人项目必备的 5 个核心事件

别一上来就埋 50 个事件。你先保证这 5 个是准的，它们对应用户生命周期的 5 个关键节点：

1. signup_completed：用户是谁。没有注册就用匿名 ID，但注册是身份的分水岭。
2. onboarding_finished：用户完成了新手引导。这是"激活"的起点，大量项目的流失发生在这里。
3. core_action_completed：用户第一次完成产品的核心价值动作。这是你的"aha moment"，比如生成了第一份简历、导出了第一个视频、发布了第一篇文章。
4. paywall_viewed：用户产生了付费意愿。即使还没付费，这个事件告诉你需求真实存在。
5. payment_succeeded：用户付了钱。这是唯一不需要解释的北极星。

这 5 个事件连起来，就是一条完整的漏斗：来的人 → 注册的人 → 激活的人 → 想付费的人 → 付费的人。每一级的转化率，就是你下周要优化的目标。其他的事件（分享、邀请、设置修改）等这 5 个跑顺了再加。

身份识别：从匿名访客到实名用户

用户第一次访问时，分析工具会给他一个匿名 ID（distinct_id）。他注册之后，你要调用 identify，把匿名 ID 和真实用户 ID 绑定，这样他注册前的行为（看了哪个落地页、点了哪个按钮）和注册后的行为才能连成一条完整路径。

PostHog 里这件事很简单：用户登录或注册成功后调一次 posthog.identify(userId)，历史匿名事件会自动归因到这个用户。用户退出登录时调 posthog.reset()，防止下一个用同一台设备的人串号。一个小技巧：初始化时把 person_profiles 设为 identified_only，这样匿名访客不会每人生成一条用户档案，既省事件额度，分析时也更干净——反正你真正关心的就是注册用户。

PostHog 实战：从 npm install 到第一条漏斗

下面以 Next.js App Router 项目为例，这是 vibe coding 项目最常见的技术栈。其他框架思路完全一样：初始化一次 SDK，封装一个 track 函数，全站调用。

第一步：初始化

npm install posthog-js

// app/providers.tsx
'use client'

import posthog from 'posthog-js'
import { PostHogProvider } from 'posthog-js/react'

if (typeof window !== 'undefined') {
  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    // 只给已识别用户建档案，匿名访客不占用额度
    person_profiles: 'identified_only',
    // 自动捕获页面浏览（含客户端路由跳转）
    capture_pageview: 'history_change',
  })
}

export function PHProvider({ children }: { children: React.ReactNode }) {
  return <PostHogProvider client={posthog}>{children}</PostHogProvider>
}

然后在根 layout 里包一层：

// app/layout.tsx
import { PHProvider } from './providers'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <body>
        <PHProvider>{children}</PHProvider>
      </body>
    </html>
  )
}

环境变量里放两个值：NEXT_PUBLIC_POSTHOG_KEY 是项目的 API Key，NEXT_PUBLIC_POSTHOG_HOST 是数据上报地址（Cloud 美区、欧盟区或你自托管的域名，具体以官方文档为准）。注意 Key 前面必须有 NEXT_PUBLIC_ 前缀，否则客户端读不到。

第二步：封装事件发送

不要在业务代码里到处写 posthog.capture。包一层有三个好处：改 SDK 不用全站替换、可以统一加公共属性、单元测试好 mock。

// lib/analytics.ts
import posthog from 'posthog-js'

type EventProps = Record<string, string | number | boolean | undefined>

/** 发送业务事件，服务端渲染时自动跳过 */
export function track(event: string, props?: EventProps) {
  if (typeof window === 'undefined') return
  posthog.capture(event, props)
}

/** 用户注册/登录成功后调用，把匿名行为归因到真实用户 */
export function identifyUser(userId: string, traits?: EventProps) {
  if (typeof window === 'undefined') return
  posthog.identify(userId, traits)
}

/** 退出登录时调用，防止设备共用导致串号 */
export function resetUser() {
  if (typeof window === 'undefined') return
  posthog.reset()
}

业务代码里的调用就长这样，干净得像没埋过点：

// 用户完成核心动作的地方
import { track } from '@/lib/analytics'

async function handleExport() {
  const result = await exportPdf(fileId)
  track('core_action_completed', { action_type: 'pdf_export', pages: result.pages })
}

// 注册成功回调里
import { identifyUser } from '@/lib/analytics'

identifyUser(user.id, { plan: 'free', signup_source: 'landing_v2' })

第三步：绕过广告拦截器（可选但推荐）

一个残酷的现实：相当一部分技术用户装了广告拦截器，分析脚本会被直接拦掉，你的数据会系统性低估。一个低成本的解法是反向代理——让上报请求走你自己的域名，拦截器就认不出来了。Next.js 里加几行 rewrites 就行：

// next.config.ts
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/ingest/static/:path*',
        // 按你实际使用的 PostHog 区域替换，以官方文档为准
        destination: 'https://us.i.posthog.com/static/:path*',
      },
      {
        source: '/ingest/:path*',
        destination: 'https://us.i.posthog.com/:path*',
      },
    ]
  },
}

然后把初始化里的 api_host 改成 /ingest。上报走同域，拦截率大幅下降。注意这招对 Umami/Plausible 同样适用，原理一样。

第四步：建第一条漏斗和留存表

代码埋完，去 PostHog 后台建两个视图，以后每周就看它俩：

漏斗（Funnels）：按顺序放入 signup_completed → onboarding_finished → core_action_completed → paywall_viewed → payment_succeeded，时间窗口设 7 天。它会告诉你每一步的转化率和流失人数。第一次看到这个漏斗的人，十个有九个会倒吸一口凉气——原来 80% 的注册用户连新手引导都没走完。

留存（Retention）：以 core_action_completed 为"回访事件"，看注册用户在第 1、7、30 天还有多少人回来用。留存曲线是产品健康度的体检表：首日留存低于 20%，说明产品没击中需求；7 日留存断崖，说明核心流程有摩擦。

别贪多，先把这两个视图钉在 PostHog 的 dashboard 首页。等你能对着漏斗说出"上周改了引导页第三步，激活率涨了 6 个点"，这套系统就真正转起来了。

隐私合规：别等到被投诉才补

很多独立开发者觉得"就我这点流量，谁管我合规"。但只要你有一个欧盟用户，GDPR 就适用；而且应用商店、支付平台对隐私政策的要求越来越严。合规不是大公司的专利，它是上线清单里的一项，顺手就能做。

三件事必须做：

• Cookie 同意横幅：欧盟用户首次访问时弹横幅，用户点"接受"之前不要初始化分析 SDK。实现上很简单：把 posthog.init 推迟到用户同意之后；或者先 posthog.opt_out_capturing()，同意后再 posthog.opt_in_capturing()。横幅本身不用自己写，开源组件一抓一大把。
• 隐私政策写清楚：在隐私政策里写明你用了哪个分析工具、收集哪些事件、数据存哪儿（比如 PostHog 欧盟区）、用户如何要求删除数据。AI 写隐私政策很快，但你要逐条核对，别让它编一个你没做的承诺。
• 数据保留期：给事件数据设一个保留期限（比如 12 个月），到期自动清理。PostHog 支持配置数据保留策略，具体以官方文档和你的套餐为准。存着用不上的陈年数据，除了增加泄露风险，没有任何价值。

另外提醒一句：永远不要把密码、token、身份证号这类敏感信息放进事件属性。PostHog 默认会捕获页面 URL 和文本内容里的一些信息，表单页要检查自动捕获有没有把用户输入带进去。这是埋点事故里最常见也最致命的一类，出一次就可能毁掉用户信任。

用数据做决策：每周只看三张表

数据本身不产生价值，决策才产生。很多人的误区是 dashboard 建了十几个，一周看一次，看完什么都不改。对一人团队，我建议每周只看三张表，每张表对应一个行动：

表	看什么	触发什么行动
流量与来源	每周访客数、各渠道占比、落地页跳出率	某个渠道流量大但注册转化低 → 落地页文案或首屏出了问题，改一版再测
激活漏斗	注册→引导完成→核心动作的每步转化率	引导完成率低 → 砍掉引导步骤或加进度提示；核心动作转化低 → 把核心功能入口往前挪
留存与付费	7 日留存曲线、paywall 查看→付费转化率	留存断崖 → 去找流失用户聊（发 5 封邮件比看 5 张表管用）；付费转化低 → 检查定价页是否讲清楚了价值

举两个真实的决策例子。第一个：某工具站发现 Product Hunt 来的流量占 40%，但注册转化率只有自然搜索流量的三分之一。结论不是"PH 没用"，而是 PH 用户是来猎奇的，落地页首屏要加一句"30 秒生成第一份简历"这种即时价值承诺，而不是讲品牌故事。改完转化率翻倍。

第二个：一个 AI 写作工具发现 onboarding_finished 到 core_action_completed 的转化只有 15%。埋点细化后发现，用户卡在"选择写作模板"这一步——选项太多。砍掉模板选择，默认给一个通用模板，转化提到 41%。这个改动只花了一个下午，但如果没有漏斗数据，作者可能还在优化他引以为傲的模板库。

注意这两个例子的共同点：数据只负责定位问题，解决方案来自你对用户的理解。埋点告诉你"哪一步掉了 60% 的人"，但"为什么掉"永远要靠你去跟用户聊、去自己走一遍流程。数据是 CT，不是诊断书。

成本控制：别让免费额度在月底爆掉

PostHog 这类工具按事件量计费，免费额度对一人项目通常绰绰有余，但有两个隐形杀手：自动捕获（autocapture） 和 高频事件。autocapture 会把每一次点击、每一次输入都记下来，一个重度用户一天就能产生上千条事件。我的建议是：开发阶段可以开着 autocapture 找灵感，上线前关掉，只保留你设计的 5 个核心事件和必要的页面浏览。

另一个常见浪费是把"心跳""滚动深度""鼠标移动"这类高频事件全量上报。真想看用户有没有读完长文章，正确做法是只在滚动到 25%、50%、100% 这三个阈值时各发一次，而不是每滚动一像素发一次。埋点和写代码一样，克制是一种美德。

最后，每月初花五分钟看一眼用量 dashboard。如果事件量逼近免费额度上限，先检查是不是 autocapture 忘了关，或者某个循环里误调了 track——我见过有人在 useEffect 里没写依赖数组，一个页面刷出几万条事件。额度是拿来分析用户的，不是拿来喂 bug 的。

上线检查清单：发布前逐项打勾

把下面这张清单存下来，每次上线新项目时过一遍。全部打勾最多花半天，但能帮你避开 90% 的埋点返工：

• SDK 已初始化，生产环境能实时看到测试事件（先自己走一遍流程，确认 5 个核心事件都触发）
• 事件命名符合 动词_对象 规范，文档里记了一笔（哪怕只是 README 里的一张表）
• 注册/登录成功后调用了 identify，退出登录调用了 reset
• 反广告拦截的反向代理已配置（或确认目标用户群拦截率可接受）
• 漏斗视图已建好：注册 → 引导完成 → 核心动作 → 付费墙 → 付费成功
• 留存视图已建好，回访事件选的是真正的核心动作
• Cookie 同意横幅已上线，未同意前不初始化 SDK
• 隐私政策写明了分析工具、收集范围、数据存储位置和删除方式
• 事件属性里没有密码、token 等敏感信息，表单页检查过自动捕获
• 数据保留期已设置，不过期囤积

最后说一句大实话：埋点这件事，完美主义是最大的敌人。我见过有人花两周时间设计"完美的事件体系"，结果产品上线三个月还没人用，事件设计得再漂亮也是零。正确的顺序永远是：先上线，先有用户，先埋 5 个核心事件，跑起来再说。数据分析是帮你把 1 做到 10 的工具，不是 0 到 1 的前提。眼睛要装，但别为了装眼睛耽误了走路。