為 VitePress 部落格加上 Vercel Analytics

部落格上線一陣子後，總會好奇有多少人來看、哪些文章比較受歡迎、網站跑起來順不順。 原本在考慮要不要裝 Google Analytics，但想到它那肥大的 script 和 Cookie 同意的麻煩，就覺得有點煩。 後來發現 Vercel Analytics 超輕量又不用處理 Cookie 問題，整合起來也簡單，這篇就來記錄一下實作過程。

---

為什麼選 Vercel Analytics？

在決定用哪套分析工具之前，我其實看了好幾個選項：

Google Analytics 雖然功能強大，但 script 太肥、載入慢，而且要處理 Cookie 同意橫幅，感覺有點麻煩。

Plausible / Fathom 這類隱私友善的分析服務都不錯，但要付費，而且要多維護一個服務。

最後選了 Vercel Analytics 的原因很簡單：

1. 超輕量：script 只有約 1 KB，比 Google Analytics 小 45 倍
2. 不用 Cookie：完全符合 GDPR，不需要同意橫幅
3. 自動追蹤 Web Vitals：LCP、INP、CLS 這些效能指標都有，對 SEO 很重要
4. 無痛整合：部落格本來就在 Vercel 上，加幾行程式碼就搞定
5. 即時資料：不用等好幾個小時才看到數據

---

Vercel Analytics vs Google Analytics

在選擇分析工具時，很多人第一個想到的都是 Google Analytics，但其實兩者的定位和使用情境蠻不一樣的。我整理了一個比較表：

項目	Vercel Analytics	Google Analytics (GA4)
Script 大小	~1 KB	~45 KB
效能影響	極小	明顯
Cookie	不使用	使用
GDPR 合規	預設合規	需要同意橫幅
設定難度	超簡單（幾行程式碼）	複雜（需要設定追蹤 ID、事件等）
Web Vitals	自動追蹤（LCP、INP、CLS）	需要另外設定
即時資料	是	延遲數小時
使用者行為分析	基本	深入
轉換追蹤	有限	完整
費用	免費（50K events/月） Pro: $10/月（100K events/月）	完全免費
資料所有權	Vercel	Google

我的使用建議

選 Vercel Analytics 如果你：

• 部落格已經在 Vercel 上
• 只想知道基本的流量和效能數據
• 在意網站載入速度
• 不想處理 Cookie 同意問題
• 想要即時看到資料

選 Google Analytics 如果你：

• 需要深入的使用者行為分析
• 要追蹤轉換和目標達成
• 需要自訂報表和細緻的區隔
• 要整合 Google Ads 等其他 Google 服務
• 不在意多一點效能負擔

我的作法：

對個人部落格來說，Vercel Analytics 就很夠用了。它輕量、快速、資料也夠清楚。 如果真的需要更深入的分析，兩個一起用也可以，只是要記得處理 GA 的 Cookie 同意問題。

---

實作步驟

第一步：安裝套件

首先要把 @vercel/analytics 套件裝起來。

我的專案用的是 pnpm：

pnpm add @vercel/analytics

如果你用 npm 或 yarn：

npm install @vercel/analytics
# 或
yarn add @vercel/analytics

---

第二步：初始化 Analytics

接下來要在 VitePress 主題設定檔中初始化 Analytics。

打開 docs/.vitepress/theme/index.ts，加入以下程式碼：

import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { inject } from '@vercel/analytics'
import './custom.css'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // 你原有的元件註冊...

    // 初始化 Vercel Analytics（僅在客戶端執行）
    if (typeof window !== 'undefined') {
      inject()
    }
  }
} satisfies Theme

這段程式碼做了幾件重要的事：

1. 客戶端檢查：if (typeof window !== 'undefined') 確保只在瀏覽器環境執行，避免 SSR 階段出錯
2. TypeScript 類型：import type { Theme } 和 satisfies Theme 可以獲得完整的型別檢查
3. 初始化時機：在 enhanceApp 中初始化，確保應用程式啟動時就開始追蹤

---

第三步：部署到 Vercel

把變更推到 GitHub，Vercel 就會自動觸發部署：

git add .
git commit -m "Add Vercel Analytics"
git push origin main

部署完成後，等個幾分鐘讓 Analytics 開始收集資料。

---

第四步：查看分析資料

1. 登入 Vercel Dashboard
2. 選擇你的專案
3. 點擊上方的 Analytics 分頁

你會看到以下資料：

• 頁面瀏覽量：哪些頁面最受歡迎
• 訪客數量：不重複訪客統計
• 地理位置：訪客來自哪些國家/地區
• 裝置類型：桌面、平板、手機的比例
• Web Vitals：LCP（最大內容繪製）、INP（互動到下次繪製）、CLS（累積版面配置位移）等效能指標

---

進階用法：追蹤自訂事件

基本的頁面瀏覽追蹤設定好之後，如果想追蹤更具體的使用者行為（例如：點按鈕、送出表單、留言等），可以用 track 函式。

範例：追蹤留言提交

假設你的部落格有 Waline 留言系統，想知道有多少人提交留言：

import { track } from '@vercel/analytics'

// 在留言提交成功後呼叫
track('comment_submitted', {
  article: '文章標題或 URL',
  category: 'notes' // 或 'learn', 'misc'
})

範例：追蹤外部連結點擊

如果想知道有多少人點了文章中的外部連結：

<script setup lang="ts">
import { track } from '@vercel/analytics'

const trackExternalLink = (url: string) => {
  track('external_link_click', { url })
}
</script>

<template>
  <a
    href="https://example.com"
    @click="trackExternalLink('https://example.com')"
    target="_blank"
  >
    外部連結
  </a>
</template>

在 Vercel Dashboard 查看自訂事件

自訂事件會出現在 Analytics → Events 分頁，可以看到：

• 事件發生次數
• 事件參數（例如：文章名稱、URL 等）
• 時間序列圖表

---

開發環境注意事項

在本地開發時（pnpm dev），Analytics 不會送資料，這是預期的行為：

• 避免開發時的測試資料污染正式統計
• 不會影響開發體驗
• 只在 production build 生效

如果想在本地測試 Analytics，可以用 production 模式預覽：

pnpm build
pnpm serve

---

效能影響

Vercel Analytics 的 script 真的超輕量：

• Script 大小：約 1 KB，比 Google Analytics（約 45 KB）小 45 倍
• 載入方式：非同步載入，不會卡住頁面渲染
• 執行時機：在頁面 load 事件後才執行
• 網路請求：只在必要時才送資料

官方數據顯示，Vercel Analytics 是 44x smaller than Google Analytics，對網站效能的影響真的小很多。

---

隱私與合規

Vercel Analytics 在隱私方面做得不錯：

1. 不用 Cookie：完全符合 GDPR 規範
2. 匿名追蹤：不收集個人識別資訊
3. 無第三方追蹤器：資料只在 Vercel 內部處理
4. 透明的資料政策：Vercel Privacy Policy

這表示你不用在網站上放煩人的 Cookie 同意橫幅，使用者體驗好很多。

---

常見問題

Q: 免費版有限制嗎？

Vercel Analytics 的免費版（Hobby Plan）包含：

• 每月 50,000 events（2025 年更新，之前是 2.5K）
• Events 包含頁面瀏覽、Web Vitals 等所有追蹤事件
• 基本的流量統計和 Web Vitals 監控

重要限制：

• 所有專案共用額度：同一個 Vercel 帳號下的所有專案會累加計算
• 超過後會暫停收集：超過限制有 3 天寬限期，之後停止收集資料
• 要等 7 天才會重新開始，或者升級到 Pro Plan
• 僅限個人非商業用途

Pro Plan 的差異：

• 每月 100,000 events
• 超過後可以付費繼續使用
• 可用於商業專案

對一般個人部落格來說，50K events/月應該很夠用了。真的超過的話再考慮升級。

Q: 什麼是 Events？跟頁面瀏覽有什麼不同？

Events 是 Vercel Analytics 計算用量的單位，包含所有追蹤的資料點：

• 頁面瀏覽（Page Views）
• Web Vitals 數據（LCP、INP、CLS 等）
• 自訂事件（如果你有用 track() 函式）

舉例來說： 一個使用者造訪你的部落格文章，可能會產生：

• 1 個頁面瀏覽 event
• 3 個 Web Vitals events（LCP、INP、CLS 各 1 個）
• 總共 4 個 events

所以 50K events/月 並不等於 50K 頁面瀏覽，實際上大約是 12,500 次頁面瀏覽左右（假設每次瀏覽產生 4 個 events）。

Q: INP 是什麼？為什麼不是 FID？

INP（Interaction to Next Paint） 是 Google 在 2024 年 3 月推出的新 Core Web Vital 指標，用來取代舊的 FID（First Input Delay）。

主要差異：

• FID：只測量「第一次」使用者互動的延遲
• INP：測量頁面上「所有」互動的回應速度，更能反映真實的使用體驗

INP 會追蹤所有的點擊、按鍵、輸入等互動，並記錄從互動到畫面更新的時間。這對 SEO 很重要，因為 Google 搜尋排名會參考這個指標。

Q: 可以和 Google Analytics 一起用嗎？

可以！兩個不衝突，你可以同時用：

• Vercel Analytics 看即時資料和 Web Vitals
• Google Analytics 做更深入的使用者行為分析

但老實說，對一般部落格來說，Vercel Analytics 就夠用了。

Q: 資料可以匯出嗎？

Pro Plan 以上可以透過 Vercel API 匯出原始資料，但 Hobby Plan 只能在 Dashboard 看。

---

總結

整合 Vercel Analytics 到 VitePress 其實超簡單，主要就是：

1. 裝套件
2. 加幾行程式碼初始化
3. 推到 Vercel 部署
4. 開始收集資料

用起來的感覺很不錯，輕量、快速、不用處理 Cookie 問題，還能追蹤 Web Vitals。 如果你的部落格本來就在 Vercel 上，真的沒理由不用！

包括你正在看的這個部落格，也是用 Vercel Analytics 在追蹤流量和效能指標。

---

參考資源

• Vercel Analytics 官方文件
• @vercel/analytics NPM 套件
• VitePress 官方文件