安裝 AI 爬蟲追蹤
Cloudflare、Vercel、WordPress、自建 Node 伺服器、Webflow 與 Shopify 的逐步安裝指南。
本頁逐步說明每一種安裝方式。爬蟲追蹤衡量哪些項目、驗證如何運作,請參閱 AI 爬蟲。同一套安裝也會回報由 AI 回答引薦的 真人造訪,因此完成安裝後,AI 流量也會有資料; 該頁面的純瀏覽器安裝選項,請參閱安裝 AI 流量追蹤。
請依網站的執行環境選擇對應的指南:
| 你的環境 | 適用指南 |
|---|---|
| 網站位於 Cloudflare 後方(橘色雲代理) | Cloudflare Worker |
| 部署在 Vercel 上的 Next.js 應用程式(或自行架設的 Next.js) | Vercel / Next.js 中介軟體 |
| WordPress 網站 | WordPress 外掛 |
| 架設在自有伺服器上的自行開發網站(AWS、GCP、Azure、VPS、容器) | 自建伺服器 / Node |
| Webflow 網站 | Webflow |
| Shopify 商店 | Shopify |
開始之前:產生網站金鑰
無論使用哪個平台,每種安裝方式都需要網站金鑰:
- 在應用程式中前往設定 → 連線 → 網站追蹤。
- 點選產生網站金鑰。為金鑰命名,最好也填寫它要回報的網域;填寫網域還能 強化該網站已簽章爬蟲的驗證。
- 從確認對話框中複製兩個值:金鑰 ID 與簽章密鑰(以
ctk_開頭)。 簽章密鑰只會顯示一次;如果遺失,請對該金鑰使用輪換,產生新的密鑰。
請妥善保管簽章密鑰:任何取得密鑰的人,都能以你的網站名義提交偽造的流量回報。
Cloudflare、Vercel 與自建伺服器的程式碼片段會從名為 CITLYZE_SIGNING_SECRET 的
環境變數讀取密鑰,因此它不會出現在你的程式碼中;WordPress 外掛則將它儲存在外掛
設定裡。絕不要將它提交到程式碼儲存庫,也不要貼到用戶端程式碼中。
Cloudflare Worker
如果你的 DNS 託管在 Cloudflare,且網站已開啟代理(橘色雲開關),請使用這個方式。 這是最完整的選項:它在邊緣看得到每一個請求、會回報真實的 HTTP 狀態碼,而且無論 Cloudflare 後方執行的是什麼都能運作。
- 在設定 → 連線 → 網站追蹤 → 安裝程式碼片段中開啟 Cloudflare 分頁, 並複製程式碼片段。
- 將程式碼片段中的
SITE_KEY_ID換成你的金鑰 ID。簽章密鑰不要寫進程式碼; 你會在第 5 步將它新增為 Worker 機密。 - 在 Cloudflare 控制台中,前往
Workers & Pages → Create → Create Worker。為它命名(例如
ai-crawler-tracker),然後點選 Deploy 建立空白的 Worker。 - 點選 Edit code,將自動產生的範例換成你的程式碼片段,再點選一次 Deploy。
- 新增簽章密鑰:在 Worker 中開啟 Settings → Variables and Secrets → Add,
類型選擇 Secret,命名為
CITLYZE_SIGNING_SECRET,貼上你的簽章密鑰, 然後點選 Deploy。Cloudflare 會加密儲存密鑰,它永遠不會出現在 Worker 的 程式碼中。 - 將 Worker 連接到你的網站:開啟該 Worker 的 Settings →
Domains & Routes → Add → Route,選擇你的區域(zone),並新增路由
example.com/*。如果網站也透過www.example.com提供服務,請再為www.example.com/*新增一條路由。 - 完成:網站程式碼不需要任何修改。Worker 會把每個請求原封不動地轉送到你的 原始伺服器,並在背景回報符合條件的造訪。
有兩點需要檢查:
- 路由必須涵蓋所有路徑(
/*),否則爬蟲造訪未設定路由的頁面時,你將看不到。 - 如果這些路由上已經在執行 Worker,由於 Cloudflare 每條路由只會執行一個 Worker, 請將程式碼片段的邏輯合併到現有的 Worker,而不是再新增一個。
Vercel / Next.js 中介軟體
適用於部署在 Vercel 上的 Next.js 應用程式。同一個檔案也能用於自行架設的 Next.js。
- 在設定 → 連線 → 網站追蹤 → 安裝程式碼片段中開啟 Vercel / 反向代理 分頁,並複製程式碼片段。
- 在你的 Next.js 儲存庫中,於專案根目錄(如果應用程式位於
src/,則在src/中)建立middleware.ts,並貼上程式碼片段。 - 將
SITE_KEY_ID換成你的金鑰 ID。簽章密鑰不要寫進這個檔案。 - 在 Vercel 專案中開啟 Settings → Environment Variables,為每個要追蹤的
環境新增
CITLYZE_SIGNING_SECRET,值為你的簽章密鑰,並將它標記為 Sensitive。如果是自行架設 Next.js,請在伺服器環境中設定同一個變數。 - 如果你已經有
middleware.ts,請不要再新增第二個檔案,因為 Next.js 只會 執行一個。將程式碼片段中的輔助程式區塊複製到現有檔案,在中介軟體函式的開頭 呼叫它的回報邏輯,並確認matcher設定仍涵蓋所有路徑。 - 提交並部署。
注意事項:
- 中介軟體在回應產生之前執行,因此事件的 HTTP 狀態會回報為
unknown。這是 正常現象。如需狀態碼,請改用 Vercel log drain 取代這個中介軟體(兩者同時使用會讓每次造訪都被計算兩次),或改用 Cloudflare 或自建伺服器的安裝方式,它們也會回報重新導向。 - 在 Vercel 上,訪客 IP 取自平台設定的標頭,可以信任。如果你在自己的代理伺服器 後方自行架設 Next.js,請確認程式碼片段讀取的轉送 IP 標頭是由你的代理伺服器 設定,而不是從用戶端直接傳入。
WordPress 外掛
適用於任何可以安裝外掛的 WordPress 網站。
同一個外掛也能免費檢查你的 robots.txt 允許哪些 AI 爬蟲進入,以及是什麼擋住了其他爬蟲;請參閱 WordPress 外掛。
-
在 WordPress 後台前往外掛 → 安裝外掛,搜尋 AI Crawler Control by Citlyze,點選立即安裝,再點選啟用。 這個外掛已列在官方的 WordPress.org 外掛目錄, 不需要上傳 zip 檔。
-
想手動安裝嗎?在設定 → 連線 → 網站追蹤 → 安裝程式碼片段中開啟 WordPress 分頁,點選下載外掛(Download plugin),然後在 外掛 → 安裝外掛 → 上傳外掛中上傳 zip 檔。
-
前往 Citlyze → Connect Citlyze,填寫全部三個欄位:
- Tracker base URL:
https://app.citlyze.com - Key ID:你的金鑰 ID
- Signing secret:你的
ctk_...簽章密鑰 填入 Tracker base URL 之前,外掛不會回報任何資料。
- Tracker base URL:
-
點選發送測試事件(Send test event)。你應該會看到「已連線」的確認訊息, 表示你的憑證與網路連線從頭到尾都正常運作。
-
如果網站位於 Cloudflare 以外的代理伺服器或負載平衡器後方,請在 Visitor IP behind a proxy 中選擇代理伺服器設定的標頭,並列出代理伺服器的 位址,以便依真實 IP 驗證爬蟲。位於 Cloudflare 後方則不需要任何設定。
外掛會在每個頁面送出之後回報,並附上確切的狀態碼,包括在頁面算繪前就被其他外掛 重新導向的請求。事件會先保存在你的 WordPress 資料庫中,再分批傳送; Connect Citlyze 畫面會顯示有多少事件正在等待,以及最近一次送達的時間。
注意:由全頁快取直接提供的頁面、由網頁伺服器或 CDN 執行的重新導向,以及在 WordPress 載入前就被防火牆擋下的請求,都不會到達外掛。Connect Citlyze 畫面偵測到 頁面快取時會提醒你。如果你的網站大量使用快取,建議改用 Cloudflare Worker 安裝 方式,或上傳伺服器記錄檔。
自建伺服器 / Node
適用於你自行架設的自行開發網站:AWS、Google Cloud、Azure、VPS 或容器。這個 程式碼片段是適用於 Node 20 以上版本的 Express 風格中介軟體(也能在 Bun 與 Deno 上執行)。
- 在設定 → 連線 → 網站追蹤 → 安裝程式碼片段中開啟自建伺服器 / Node 分頁,並複製程式碼片段。
- 將它儲存為
aeo-tracker.mjs,放在伺服器進入點旁邊。 - 將
SITE_KEY_ID換成你的金鑰 ID,並在伺服器上將環境變數CITLYZE_SIGNING_SECRET設為你的簽章密鑰:可以在主機服務的機密設定中設定, 或寫在絕不提交的.env檔案中。簽章密鑰絕不能寫進程式碼片段檔案本身。 - 在路由之前註冊中介軟體:
import { aeoCrawlerTracker } from "./aeo-tracker.mjs"; app.use(aeoCrawlerTracker()); - 如果伺服器位於負載平衡器或反向代理(nginx、ALB)後方,請設定 Express 信任它
(例如
app.set("trust proxy", 1)),讓中介軟體回報真實的用戶端 IP,而不是 代理伺服器的 IP。爬蟲身分驗證檢查的就是這個 IP。 - 部署。中介軟體會在每次回應完成後才回報,因此不會增加延遲,而且包含真實的 HTTP 狀態碼。
沒有使用 Express 嗎?回傳的處理函式接受一般的 (req, res, next) 參數,也能改用於
Fastify、Koa 或 Node 的 http 伺服器。如果是完全不同的語言(Python、Go、PHP、
Ruby 等),請實作
簽章信標協定;
每個經過簽章的 HTTPS POST 最多可以包含 50 個符合條件的請求。
Webflow
Webflow 自己的代管服務無法執行伺服器端程式碼,瀏覽器端的指令碼也看不到 AI 訓練 爬蟲,因此追蹤必須安裝在 Webflow 前方的代理層:
- Webflow 的 Enterprise 方案支援自行管理的反向代理;請與你在 Webflow 的 聯絡人安排,並讓網域經由你的代理伺服器(Cloudflare、CloudFront、Fastly 或你 自己的 nginx)路由。
- 在該代理層安裝追蹤器:
- 代理伺服器在 Cloudflare 上 → 依照 Cloudflare Worker 指南操作。
- 你自己的 Node 代理伺服器 → 依照 自建伺服器 / Node 指南操作。
- 其他情況 → 在代理伺服器中實作 簽章信標協定。
- 依照下文說明進行驗證。
Webflow Cloud 應用程式無法用來追蹤整個網站:它們只處理掛載路徑下的請求,因此永遠 看不到爬蟲對一般頁面的造訪。
Shopify
標準 Shopify 店面無法執行這個追蹤器:Shopify 不允許商家在店面請求上執行伺服器端 程式碼,也不支援在商店前方架設代理伺服器(例如 Cloudflare)。瀏覽器端指令碼也 不是替代方案:AI 訓練爬蟲從不執行 JavaScript,而且瀏覽器指令碼會讓你的簽章密鑰 外洩。
你可以這樣做:
- 以 Hydrogen 建構、託管在 Oxygen 上(或任何自行架設環境)的 Headless 店面會執行伺服器端程式碼;請將 自建伺服器 / Node 程式碼片段的邏輯接入店面伺服器的請求 處理程式。
- 如果是標準商店,Citlyze 的其他測量功能(提示詞追蹤、引用、GEO 稽核)不受商店 託管位置影響,照常運作。
驗證安裝
- 在設定 → 連線 → 網站追蹤中,網站金鑰表格有一欄最後事件。你的安裝送出 第一份被接受的回報後,這一欄就會更新;爬蟲造訪與 AI 引薦點擊都算。
- WordPress 使用者可以用發送測試事件(Send test event)立即確認是否能送達 (測試事件會驗證憑證與網路連線,但不會更新最後事件)。
- 請耐心等候:流量較低的網站,第一次真實的爬蟲造訪可能需要幾小時到幾天。事件 開始送達後,診斷 → AI 爬蟲活動 → 總覽就會出現資料。
- 如果過了幾天仍然沒有資料,請重新檢查:程式碼片段(或外掛設定)中的金鑰 ID
是否屬於一把有效、未撤銷的金鑰;
CITLYZE_SIGNING_SECRET是否為該金鑰目前的 簽章密鑰;以及你的路由或中介軟體是否涵蓋所有路徑。沒有有效的簽章密鑰時, 程式碼片段不會回報任何資料,並會記錄一次「Citlyze crawler tracking is off」。 - 網站金鑰表格也會顯示每把金鑰所使用的收集器版本,並在程式碼片段或外掛有新版本, 或 WordPress 外掛偵測到頁面快取時提醒你。