> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据分析 & 站长工具

> 一次接入 Vercel、GA4、PostHog、Plausible、Umami、Clarity 六家分析工具，外加 GSC、Bing Webmaster、Yandex Webmaster 一行配置的所有权验证。每家按 env 变量自动决定是否启用，自由组合。

数据分析是那种"以后再加"的决策 —— 拖一拖就累积成几小时的集成工作。AI 产品上线
第一天通常就需要产品分析(PostHog)+ 流量分析(Plausible / GA),不是上线 60 天后
才来补。

vibestrap 在 root layout 里挂了一个 `<Analytics />`,把数据同时发到 **六家**
provider(Vercel、GA4、PostHog、Plausible、Umami、Clarity),外加
`metadata.verification` 块给 Google / Bing / Yandex 站长工具用。每个 loader 自己
检查 env 变量,没配就返回 `null` —— 你只为配过的 provider 付代价,配 env、重启、
搞定。

## 分析 provider

### 前置条件

* 在 Vercel、Google Analytics 4、PostHog、Plausible、Umami、Microsoft Clarity
  里挑至少一家注册。
* 拿到 provider dashboard 里的 site / property / website ID。
* 一个生产域名（部分 provider 拒绝来自 `localhost` 的事件，或者直接采样掉）。

### 一步步配置

1. **在 `src/config/site.ts` 选要启用的 provider**。六个默认全是 `true`；
   想关掉就设 `false`，即便 env 变量配了也不会渲染。

   ```ts theme={null}
   analytics: {
     vercel: true,
     googleAnalytics: true,
     posthog: true,
     plausible: true,
     umami: true,
     clarity: true,
   },
   ```

2. **把对应的 env 变量加到 `.env.local`**。全部是 `NEXT_PUBLIC_*`——loader 跑在
   浏览器里，所以必须打进客户端 bundle。

   ```bash theme={null}
   # GA4 —— Measurement ID
   NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

   # PostHog —— project key + host（host 默认 us.i.posthog.com）
   NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

   # Plausible —— 域名 + host（host 默认 plausible.io）
   NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
   NEXT_PUBLIC_PLAUSIBLE_HOST=https://plausible.io

   # Umami —— website ID + host（host 默认 cloud.umami.is）
   NEXT_PUBLIC_UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000
   NEXT_PUBLIC_UMAMI_HOST=https://cloud.umami.is

   # Microsoft Clarity —— 项目 ID，从 clarity.microsoft.com 拿
   NEXT_PUBLIC_CLARITY_PROJECT_ID=xxxxxxxxxx
   ```

3. **Vercel Analytics 在 Vercel 上零配置**——`@vercel/analytics/next` 组件会自动
   注入脚本。本地是 no-op。要关掉就设 `analytics.vercel = false`。

4. **重启 `pnpm dev`** —— `NEXT_PUBLIC_*` 是构建时打进去的，不重启不会生效。

### 怎么挑

| Provider          | 适用场景                                    |
| ----------------- | --------------------------------------- |
| Vercel Analytics  | 已经部署在 Vercel 上、想要个零配置的基线。免费额度够用。        |
| GA4               | 要做 Google Ads 归因、或者市场团队已经在用 GA。         |
| PostHog           | 产品分析、feature flag、session 录屏一站式。免费额度大方。 |
| Plausible         | 隐私优先，GDPR 友好，不用 cookie banner。脚本很轻。     |
| Umami             | 开源、可自托管。隐私优势同 Plausible，自托管更省钱。         |
| Microsoft Clarity | 热图 + session 录屏，永久免费、无流量上限。和 GA4 配合非常顺。 |

### 验证生效

1. 用无痕窗口打开站点。
2. 打开 devtools → Network，按 provider 域名过滤（如 `posthog.com`、
   `plausible.io`、`clarity.ms`），页面加载时应该至少看到一个请求发出去。
3. 随便点点页面——每家 provider 的后台应该在 30 秒内出现实时访客。
4. 看页面源码：每个开启的 provider 应该有一个 `<script>` 标签，关掉的应该没有。

### 常见坑

1. **忘了 `NEXT_PUBLIC_` 前缀**。浏览器要读的变量必须带前缀。不带前缀，
   Next.js 在打包时会把它从客户端 bundle 里剥掉，loader 静默挂成 `null`。
2. **被广告拦截屏蔽**。uBlock Origin、Brave 默认会屏蔽 GA4、PostHog、Clarity、
   Umami。解决办法是走代理域名——Plausible 支持自托管的
   `/js/script.outbound-links.js` 路由，PostHog 也有 reverse-proxy 教程。
3. **GA4 在欧盟要 consent banner**。GDPR 要求 GA4 显式 opt-in。Clarity 同理
   （session 录屏 = 个人数据）。要么把脚本挂在 consent 弹窗后面，要么改用
   Plausible / Umami 这种本来就不用 cookie 的。
4. **本地流量污染生产 dashboard**。dev 环境的访问会跑到生产 dashboard 里。
   要么 dev 时设 `analytics.posthog = false`，要么用 provider 的 "exclude IP" /
   "disable on localhost" 过滤器。
5. **Plausible 域名不匹配**。`NEXT_PUBLIC_PLAUSIBLE_DOMAIN` 必须和 Plausible
   后台注册的域名完全一致——`www` 写不写都得对得上。不匹配的事件会被静默丢弃。

## 搜索引擎站长工具验证

要在 **Google Search Console**、**Bing Webmaster Tools** 或 **Yandex Webmaster**
里证明站点所有权，每家后台都会让你往 `<head>` 里加一个 meta 标签。Vibestrap
通过 `src/app/layout.tsx` 里的 Next.js `metadata.verification` 来渲染这些标签，
你只需要把对应的值贴到 env 变量里就行。

### 一步步配置

1. **在每家后台添加你的域名**：
   * Google Search Console → [search.google.com/search-console](https://search.google.com/search-console)
   * Bing Webmaster Tools → [bing.com/webmasters](https://www.bing.com/webmasters)
   * Yandex Webmaster → [webmaster.yandex.com](https://webmaster.yandex.com/)

2. **选择 "HTML tag" 验证方式**。每家后台会给你一段类似的 meta 标签：

   ```html theme={null}
   <!-- Google -->
   <meta name="google-site-verification" content="ABC123..." />
   <!-- Bing -->
   <meta name="msvalidate.01" content="DEF456..." />
   <!-- Yandex -->
   <meta name="yandex-verification" content="GHI789..." />
   ```

3. **只复制 `content` 里的值**（不是整段标签），贴到 `.env.local`：

   ```bash theme={null}
   GOOGLE_SITE_VERIFICATION="ABC123..."
   BING_SITE_VERIFICATION="DEF456..."
   YANDEX_SITE_VERIFICATION="GHI789..."
   ```

   这些是**服务端** env 变量（不带 `NEXT_PUBLIC_` 前缀）——Next.js 在构建时读取
   它们生成 root metadata。

4. **想单独关掉某个标签**就改 `src/config/site.ts`（即便 env 变量已经设了，
   也会跳过渲染）：

   ```ts theme={null}
   verification: {
     google: true,
     bing: true,
     yandex: true,
   },
   ```

5. **部署上线**，然后回到每家后台点 **Verify**。

### 验证生效

```bash theme={null}
curl -s https://yourdomain.com | grep -E 'google-site-verification|msvalidate|yandex-verification'
```

每个设了的 env 变量应该有一个对应的 `<meta>` 标签。env 没设就完全不渲染，
不会出现空的 `content=""` 污染。

### 常见坑

1. **别把整段 `<meta>` 标签贴进来**——只贴 `content` 里的值。贴整段会让渲染出
   的 head 出现重复或损坏的 HTML。
2. **验证是一次性的**。后台一旦确认，env 变量可以一直留着；保留 meta 标签没
   任何额外成本。
3. **CDN 缓存**。如果部署后后台还是说 "tag not found"，去清一下 CDN 缓存
   （Cloudflare、Vercel）——验证器是去抓你的实时 HTML 的。
4. **DNS 是替代方案**。三家后台都支持 DNS TXT 记录验证，不用动 HTML。如果你
   更喜欢这种方式，env 变量留空，去 DNS provider 里加 TXT 记录。

## 官方文档

* Vercel Analytics：[vercel.com/docs/analytics](https://vercel.com/docs/analytics)
* Google Analytics 4：[support.google.com/analytics](https://support.google.com/analytics)
* PostHog：[posthog.com/docs](https://posthog.com/docs)
* Plausible：[plausible.io/docs](https://plausible.io/docs)
* Umami：[umami.is/docs](https://umami.is/docs)
* Microsoft Clarity：[learn.microsoft.com/clarity](https://learn.microsoft.com/en-us/clarity/)
* Google Search Console：[support.google.com/webmasters](https://support.google.com/webmasters)
* Bing Webmaster Tools：[bing.com/webmasters/help](https://www.bing.com/webmasters/help)
* Yandex Webmaster：[yandex.com/support/webmaster](https://yandex.com/support/webmaster/)
