流量這回事 — PostHog 踩坑全紀錄
2026.02.25
寶店長：「這個月有多少人來看我的店？」
系統：「⚠️ PostHog 數據收集中」
寶店長：「......」
如果你也在用 PostHog + Docusaurus，這篇可能省你幾個小時：
- PostHog 的
phc_和phx_API Key 有什麼不同？ - Personal API Key 在哪裡建立？（不是在 Project Settings）
- HogQL 查詢 API 一直報錯
Extra inputs are not permitted怎麼解？ posthog.opt_out_capturing()怎麼用？回傳undefined是正常的嗎？- Chrome 的書籤（Bookmarklet）新版要怎麼建？
做網站這件事，SEO 那一關好不容易搞懂了，
緊接著就是，燈燈燈燈：流量分析。
寶店長以為裝上 PostHog 就完事了。
PostHog 是一套開源的網站數據分析工具，
可以追蹤哪些人來看網站、停留多久、看了哪些頁面。
寶店長的網站從一開始就裝上它了，
還自製了一個後台連結數據。
⚠️ 從一個警告開始
某天，寶店長打開網站後台的庫存頁面，
那是一個可以查看文章上架紀錄與閱讀統計的私人頁面。
畫面上出現一行黃色警告：
⚠️ PostHog 數據收集中
數字全是零。總閱讀：0。唯一訪客：0。本週：0。
裝了那麼久，數據一筆都沒有？
真是謝謝啊。
🔑 PostHog 有兩種 API Key：phc_ 和 phx_ 差在哪？
這個問題就是，
原封不動問 Claude。
「你用的是 Project API Key（phc_ 開頭），它只負責發送事件，不能查詢數據。
要查數據，需要 Personal API Key（phx_ 開頭）。」
這不知道是民國幾年設定的，連 PostHog 怎麼進去都忘了。
好不容易又登入了 PostHog ，要來找 Personal API Key。
是我眼瞎嗎?
怎麼 Claude 說得很清楚，我找得很懷疑人生。
Settings → Project → General。
只有看到要再驗證的訊息，
只好去問 GPT 這種設定細節。
Personal API Key 不在「專案設定」裡，它在「帳號設定」裡。
PostHog API Key 種類一覽
Project API Key (phc_) | Personal API Key (phx_) | |
|---|---|---|
| 用途 | 前端追蹤（發事件進去） | 後端查詢（讀取數據） |
| 在哪裡 | Settings → Project | Settings → Account → Profile |
| 能查數據嗎？ | ❌ 不行 | ✅ 可以 |
🔐 PostHog Personal API Key 在哪裡建立？
找到了 Settings → Account → Profile，
但頁面顯示：
「Re-authentication required」
點了之後要重新登入驗證，
驗證完終於看到了 Personal API Key 的欄位，
這大概是一種另類的多巴胺噴發。
點「Create new key」。
結果，怎麼有這麼多個項目的選擇。
只好，又跑去找 GPT，要開哪些?
但問了之後覺得，好像應該要問 Claude 才對吼，耍笨。
總之，
GPT 說：最小權限原則—
能 Read 就不要給 Write，能 No access 就不要開。
Claude 說： Query 開 Read 就好，其他都不用開。
終於啊，要結束了吧，
然後很反射性地按了 OK，
非常的不 OK 啊。
因為，產生後只會顯示一次，要立刻複製。
只好，重新刪掉，再來一次，
千迴百轉，都是考驗著耐心啊。
🪲 HogQL 查詢一直報錯：Extra inputs are not permitted (kind)
拿到 Personal API Key，填進去，滿心期待地執行腳本。
PostHog API 錯誤: Extra inputs are not permitted (kind)
又錯了。
這次不是 Key 的問題，是查詢的格式包裝錯誤。
// ❌ 這樣寫是錯的
{ kind: 'HogQLQuery', query: 'SELECT ...' }
// ✅ 要多包一層 query
{ query: { kind: 'HogQLQuery', query: 'SELECT ...' } }
差一層包裝，API 就完全看不懂在說什麼。
改好之後，再執行：
總閱讀數: 1078
本週閱讀: 76
唯一訪客: 61
數字出現了。
寶店長看著螢幕，真不可置信，怎麼可能 1078 次。
一定都是我自己一直在測試啦，
這樣怎麼知道真正的讀者人數?
👣 隱藏自己的腳印
Claude 給了一個解法：
posthog.opt_out_capturing()
在瀏覽器 Console 執行這行， 就能讓 PostHog 記住「這台電腦不要追蹤我」。
AGAIN!
Claude 寫得很雲淡風輕，
我看得很懷疑人生，
我很想按照說明去設定，
但連從何開始都不知所措。
🤔 看不懂，繼續去問 GPT
「Console 是什麼？」
「這行要在哪裡執行？」
GPT 的解釋是這樣的——
PostHog 是裝在瀏覽器端的。
每次你用瀏覽器打開網站，
它就會執行、記錄你的行為、送到後台統計。
posthog.opt_out_capturing() 的意思是：
「在這個瀏覽器的 localStorage 存一個標記：我要退出追蹤。」
之後每次開網站，PostHog 看到這個標記，
就不再記錄。
看不懂，沒關係，
問到懂為止。
學習，是有坡度的，
但，成長無極限。
😱 posthog.opt_out_capturing() 回傳 undefined，還跑出紅色錯誤？
按照指示：F12 → Console → 貼上指令 → Enter。
畫面回傳 undefined，然後出現一長串紅色錯誤：
content_script.js:138 Uncaught (in promise) Error:
Attempting to use a disconnected port object
咦，這是怎麼回事？
GPT 說：「這兩件事是不同來源的。」
undefined→ 正常。這個函式本來就不回傳任何值，Console 顯示undefined就是「執行完了，沒東西要給你看」。- 那串紅色錯誤 → 跟 PostHog 無關。那是你瀏覽器某個「擴充功能」自己的問題，它的內部連線中斷了，與你做的操作無關。
確認有沒有生效，就輸入：
posthog.has_opted_out_capturing()
回傳 true，就是成功了。
🔖 PostHog Opt-out Bookmarklet：Chrome 書籤怎麼建？
GPT 說可以把指令做成「書籤（Bookmarklet）」，
點一下就執行，不用每次開 F12。
當然好啊，但找了半天，
右鍵書籤列只有「書籤管理員」，沒有「新增書籤」這個選項。
我還真是累了。
GPT 給的解法：
Chrome 改版了，最穩定的做法是：
- 打開任意網頁，按
Ctrl + D建一個普通書籤- 開「書籤管理員」（
Ctrl + Shift + O）- 找到剛才建的書籤，右鍵 → 編輯，把網址改成：
javascript:(function(){try{posthog.opt_out_capturing();alert('已停用追蹤 ✅');}catch(e){alert('找不到 posthog，請確認在正式網站頁面');}})();
已停用追蹤 ✅
非常好，成功了。
📊 PostHog 過去的流量數據如何排除自己？distinct_id 過濾方法
這個問題也很重要，我就是想知道誰是真的讀者。
GPT 的回答很誠實：
設定 opt-out 之後，未來的數據不會再包含你。但過去已經進去的，無法刪除或修改。
PostHog 的資料是「事件流」，每一筆 pageview 都是不可更改的記錄。
不過可以在 PostHog 的 Insights 做一個「乾淨版報表」，
用 distinct_id 把自己排除掉：
// 先在 Console 查出自己的 ID
posthog.get_distinct_id()
拿到 ID 後，在 Product analytics → Trends 裡加上條件：
distinct_id 不等於你的ID
終於好了!!!
一個新報表。
不過，報表是做成了，但人也累了。
至於到底有多少讀者，
就留待下回揭曉吧。
📝 這一整圈，寶店長學到什麼
一、PostHog 有兩種 Key，用途不同，位置也不同
二、API 格式要多包一層 { query: {...} }，差一點全部出錯
三、過濾自己的流量，要在「每一台裝置的每一個瀏覽器」各做一次
四、Console 回傳 undefined 不代表壞了；紅色錯誤也不一定是你造成的
五、看不懂，可以去問 GPT；GPT 也可以解釋另一個 AI 給的說明
現在還不知道觀看的數據情況，
不過，不急，慢慢來。
有緣人自然會找到這裡的。
流量數字，只是一個現象的呈現。
大家如何來逛這間店，
又是在哪停留多久，
甚至喜歡著哪篇文章。
數據只是輔助，
就像是寶店長隨時可以在店內，
看著大家自由閒逛，
但，
還是大家開心最重要啦。
祝福大家，今日的身心靈，一切安好。
🧩 延伸閱讀
© 2026 Spirit & Savor 靈食雜貨舖
系列：精選靈食・寶店長・寶店長的學習筆記
📧 spiritandsavor@gmail.com