沒有常駐程序：跟一般伺服器最大的差別

Apps Script 跟一台伺服器最根本的差別是沒有一個常駐、屬於你的程序。一般伺服器是一支持續執行的程式，開機後一直在記憶體裡等請求；Apps Script 的程式碼平時不執行，只在被觸發（有人打 web app 網址、觸發器到點、你手動按執行）時才啟動一個執行實例，跑完就結束。這個模型帶來幾個要先知道的取捨：

• 不必管主機：沒有作業系統要維護、沒有開關機、沒有閒置費用。程式碼不跑時完全不佔資源。
• 每次執行是獨立的：兩次執行之間，記憶體裡的變數不會保留。要跨執行記住東西，得寫進外部儲存（Sheet、PropertiesService、Drive）。這跟伺服器可以用行程內記憶體 cache 是相反的。
• 有執行上限：單次執行最長 6 分鐘、同時併發有數量限制。長時間或高併發的工作不適合，細節見執行配額。

理解「沒有常駐程序」才知道 Apps Script 適合什麼：短、偶發、由事件觸發的工作，例如「接一則 beacon 寫一列」「每天彙總一次」。不適合的是需要持續連線、低延遲、或狀態常駐記憶體的服務。

容器綁定 vs 獨立專案

Apps Script 專案有兩種存在形式，差別在「它跟一個 Google 檔案綁不綁定」。

容器綁定（container-bound） 的專案依附在一個具體檔案上——從某張試算表的 擴充功能 → Apps Script 開出來的專案，就綁定那張試算表。它的好處是程式裡用 SpreadsheetApp.getActiveSpreadsheet() 直接拿到那張表，不必記檔案 ID；流量統計用這種，程式跟資料表天生綁在一起，最省事。它也能存取容器檔案特有的事件（例如試算表的 onEdit、表單的 onFormSubmit）。

獨立專案（standalone） 不依附任何檔案，從 script.google.com 直接建立。它適合「不特別綁一個檔案」的工具，或要跨多個檔案操作的情境；存取試算表要用 SpreadsheetApp.openById("表的ID") 明確指定。

選擇判準很直接：這段程式主要就是服務某一個檔案嗎——是（流量統計服務那張 log 表），用容器綁定；否（一個要操作很多表的通用工具），用獨立專案。

用到的服務

Apps Script 透過一組內建服務物件操作 Google 資源，這個案例會碰到的主要是：

• SpreadsheetApp：讀寫試算表，appendRow、getRange 等，是資料的儲存層（模組三詳談）。
• ContentService：產生 web app 的回應內容，doPost 必須回傳它的輸出。
• ScriptApp：管理觸發器，時間排程彙總會用到（模組四）。
• PropertiesService：存少量 key-value 設定或狀態，適合放「上次處理到哪一列」這種跨執行要記住的小資料。

這些服務都以你的 Google 帳號身分執行、受你的授權範圍約束，授權模型是下一篇web app 部署模型的主題。

下一步

知道 Apps Script 是什麼之後，要讓它能被 blog 的 beacon 打到，得把它部署成有公開網址的 web app。部署模型、doGet/doPost、以及授權流程，見web app 部署模型。

設定每日定時執行

觸發器可以用程式建立，也可以在編輯器左側的「觸發條件」介面點選建立。用程式建立的好處是設定跟著專案走、可版本控制：

1function createDailyTrigger() {
2  ScriptApp.newTrigger("aggregateYesterday")
3    .timeBased()
4    .atHour(1)          // 每天凌晨 1 點
5    .everyDays(1)
6    .create();
7}

這段執行一次（手動按執行），就註冊了一個「每天凌晨 1 點呼叫 aggregateYesterday」的觸發器。凌晨執行是刻意的：那時流量低、raw log 當天的資料已經齊了，彙總前一天不會漏。要注意 createDailyTrigger 只該跑一次——每跑一次就多註冊一個觸發器，重複跑會變成一天彙總很多次。管理現有觸發器用 ScriptApp.getProjectTriggers() 查、deleteTrigger 刪。

彙總邏輯

彙總做的事是：讀 raw log、把同一天同一路徑的瀏覽數出來、寫進另一張「日報」工作表。核心是一個 group by：

 1function aggregateYesterday() {
 2  var ss = SpreadsheetApp.getActiveSpreadsheet();
 3  var raw = ss.getSheetByName("工作表1").getDataRange().getValues();
 4  var report = ss.getSheetByName("日報") || ss.insertSheet("日報");
 5
 6  var counts = {}; // key = "日期|路徑" → 次數
 7  for (var i = 1; i < raw.length; i++) {      // 從第 2 列起，跳過標題
 8    var d = raw[i][0];                        // 時間欄
 9    var day = Utilities.formatDate(d, "Asia/Taipei", "yyyy-MM-dd");
10    var path = raw[i][1];
11    var key = day + "|" + path;
12    counts[key] = (counts[key] || 0) + 1;
13  }
14
15  var rows = Object.keys(counts).map(function (k) {
16    var parts = k.split("|");
17    return [parts[0], parts[1], counts[k]];   // 日期、路徑、次數
18  });
19  if (rows.length) {
20    report.getRange(report.getLastRow() + 1, 1, rows.length, 3).setValues(rows);
21  }
22}

這段 group by 有一個前提要明寫出來：它假設 raw log 裡一列等於一次瀏覽。這在模組二的資料模型下成立，因為 beacon 只在頁面載入時送一次。日後若在 payload 加入其他事件型別（例如離開事件，見模組六），每次瀏覽會產生多列，而這個迴圈仍然合法執行、只是把多數瀏覽數了不只一次——數字膨脹而沒有任何錯誤訊息。膨脹的倍率不固定（離開事件會丟失一部分），所以它比整數倍的錯誤更難從數字本身看出來。屆時的修法是在迴圈裡先篩事件型別：

1if (raw[i][5] !== "view") continue;   // 只數進入事件（第 6 欄）

把這個前提寫在程式碼旁邊，是為了讓資料模型變更的人搜尋得到所有依賴它的地方。這類「條件式合法執行但已換語意」的失效方式，見假故障與靜默失效的診斷。

兩個實作決定值得說明。日期用 Utilities.formatDate 明確指定時區（這裡 Asia/Taipei），否則跨午夜的資料可能因為時區偏移被算到錯的日子。寫日報用 setValues 一次寫一整塊、不用 appendRow 逐列寫——彙總結果可能有幾十上百列，逐列 append 會慢且容易逼近執行時間，一次 setValues 快得多（呼應寫入與並發講的批次寫入）。

在 90 分鐘配額內寫得有效率

觸發器受一條配額約束：個人帳號所有觸發器每天總執行時間上限 90 分鐘，且單次一樣不能超過 6 分鐘（見執行配額）。上面那段每次 getDataRange().getValues() 把整張 raw log 讀進來——log 還小時沒問題，但累積到數十萬列後，光讀取就可能逼近 6 分鐘。

有效率的寫法是只讀增量：記住「上次彙總處理到第幾列」，這次只讀新增的部分。用 PropertiesService 存這個游標：

1var props = PropertiesService.getScriptProperties();
2var lastRow = Number(props.getProperty("lastAggregatedRow") || 1);
3var sheet = ss.getSheetByName("工作表1");
4var newCount = sheet.getLastRow() - lastRow;
5if (newCount > 0) {
6  var fresh = sheet.getRange(lastRow + 1, 1, newCount, 5).getValues();   // 5 = 目前的欄數
7  // ... 只彙總 fresh ...
8  props.setProperty("lastAggregatedRow", String(sheet.getLastRow()));
9}

那個 5 是目前的欄數，它與前面那個「一列等於一次瀏覽」是同一種前提：欄位增加時要跟著改，而讀少了不會報錯、只會讓後面的欄位變成 undefined。

兩個常數必須一起改，否則會互相抵銷。 前面那個篩選寫的是 raw[i][5] !== "view"，查的是第六欄；這裡只讀五欄時 raw[i][5] 恆為 undefined，條件恆真、每一列都被跳過、日報變成空白。兩處相隔一節、都不產生錯誤，而症狀（日報是空的）指向的位置與成因所在的位置不同。

只讀增量讓每次彙總的成本跟「昨天新增多少」成正比、而不是跟「歷史總量」成正比，執行時間就穩定、不隨資料累積膨脹。這跟資料模型與容量邊界講的分表是互補的兩招——分表縮小單張表、只讀增量縮小單次讀取，都是為了讓彙總不被歷史總量拖垮。

下一步

時間觸發器是「到點就跑」的排程。另一類觸發器是「某個事件發生就跑」，例如表單被提交——見表單與事件觸發器。

execute as 與 who has access 的分工

部署 web app 時的兩個設定，一個決定「用誰的權限跑」、一個決定「誰能呼叫」，安全含義不同。

execute as（執行身分）決定程式用誰的權限執行。 選「我」時，任何打進來的請求都以你的身分執行程式——這是必要的，因為匿名訪客沒有你試算表的寫入權，只有用你的身分才寫得進去。它的含義是：這支程式能碰的資料範圍等於你授權給它的範圍（那一張試算表），而不是呼叫者的權限。所以程式裡只該做你願意讓匿名請求觸發的事——doPost 寫一列 log 是安全的，但如果程式裡寫了「刪除整張表」的邏輯，那也會用你的權限被匿名觸發。

who has access（誰可以存取）決定誰能呼叫這個網址。 接匿名 beacon 必須選「所有人」（完全不需登入），這也表示網址一旦洩漏（而它必然公開，見下一段），任何人都能呼叫。這兩個設定合起來的效果是：一個任何人都能觸發、但只會執行你寫的那幾行、且以你的身分操作你授權的那張表的端點。

這個網址必然公開

beacon 端點的網址會被寫進每一頁的 client-side JavaScript，任何人檢視原始碼都看得到。它藏不住，這是 client beacon 架構的本質、不是設定失誤——GA、Cloudflare Web Analytics 那些的收集端點同樣是公開的。所以安全策略不能建立在「保密網址」上，而要建立在「限制這個公開端點能造成的破壞」上。

這也界定了什麼不是風險：別人拿到網址讀不到你的 Sheet，因為 doPost 只做 appendRow 然後回一個固定的 {ok:true}，不回傳任何試算表內容；他也碰不到你其他 Google 資料，因為授權範圍只綁那張表。端點是「只能寫、寫入內容固定、回應不洩漏」的，這個形狀本身就把資料外洩排除了。

實際的風險範圍

公開端點的真實風險是騷擾型的，有兩種。髒資料：有人直接對網址 POST 任意內容，往你的 log 塞垃圾列、污染統計。配額消耗：有人狂打這個端點，吃掉你的執行配額，嚴重時排擠正常 beacon（配額的細節見配額、濫用與隱私）。

這兩種風險的共通點是它們不會洩漏或破壞你的資料，只會污染統計或耗資源。對沒沒無聞的個人 blog，攻擊者缺乏動機花力氣灌一個小站的瀏覽計數，實際發生機率低。所以務實的姿態是：先讓公開端點跑著、把「限制破壞範圍」的保護當成「遇到再加」的選項，而不是上線前就必備。具體的防護手段在下一篇。

更新部署不換網址（安全角度）

日常維護會反覆改 doPost，改完要讓 /exec 反映新版本、而網址不變——用「管理部署作業 → 編輯 → 版本選新版本」，不要用「新增部署作業」（那會產生新網址）。這個操作除了避免假故障（見web app 部署模型），也有安全意義：換網址意味著舊網址可能還殘留在快取的頁面裡繼續被打，管理起來多一個要追蹤的公開端點。用同一個部署更新，公開端點就始終只有一個、行為可控。

下一步

存取權限的安全框架清楚後，配額實際會怎麼碰撞、怎麼擋濫用、隱私怎麼守、以及量大到該遷移的訊號，見配額、濫用與隱私。

概念位置

部署有兩個決定端點行為的設定。執行身分（execute as） 決定程式用誰的權限跑：選「我」時，匿名訪客送來的請求也用你的身分執行，才能存取你的試算表。誰可存取（who has access） 決定誰能呼叫這個網址：接收匿名訪客的 beacon 必須選「所有人」，因為訪客沒有登入 Google。

可觀察訊號與例子

一個實務要點是部署與網址的關係：每次「新增部署作業」會產生一個新網址，但改完程式後應該用「管理部署作業」更新既有部署，網址才不變。用錯方式會讓前端指向舊網址、以為程式沒生效。

判讀方式

誰可存取設為「所有人」後，要判斷的是匿名端點被濫用的風險有多大：存取權限的安全含義見模組五。

doGet 與 doPost：兩個進入點

web app 對外的行為由兩個特殊函式定義。收到 GET 請求時，Google 平台呼叫 doGet(e)；收到 POST 請求時呼叫 doPost(e)。參數 e 帶著請求內容：doGet 從 e.parameter 拿 query string，doPost 從 e.postData.contents 拿請求主體。流量統計的 beacon 用 sendBeacon 送 POST，所以接收端實作 doPost，從 e.postData.contents 讀那串 JSON 字串。

兩個函式都必須回傳一個 ContentService 或 HtmlService 的輸出，這是平台的硬性要求——不回傳會被當成執行沒有正常結束。詳細用法見知識卡 doGet / doPost。

值得先記住的一條限制是 Apps Script 沒有 doOptions，所以它無法回應跨網域請求的 CORS preflight。這條限制決定了前端 beacon 必須用不觸發 preflight 的方式送，是前端 beacon 與 CORS 障礙的核心。

exec 與 dev：兩種網址

部署 web app 後會遇到兩個結尾不同的網址，用途不一樣，搞混會在測試時卡住。

/exec 是正式版網址：它對應你「部署」的那個版本、網址固定不變、遵守你設定的「誰可以存取」。blog 的 beacon 要填的是這個。/dev 是測試版網址：它永遠對應編輯器裡最新存檔的程式碼（不必重新部署就生效），但它只有對這個專案有編輯權的人（也就是你，登入狀態下）能存取。/dev 適合你自己邊改邊測，/exec 才是給匿名訪客用的。

因為 /dev 要登入、/exec 才允許匿名，用 /dev 當 beacon 端點會讓所有沒登入的訪客都被擋掉——這是一個容易誤用的點。beacon 一律用 /exec。

更新部署為什麼要用同一個網址

改完程式後怎麼讓 /exec 反映新版本，是另一個容易出錯的地方。Apps Script 有兩個看起來都能「部署」的入口：新增部署作業 會產生一個全新的 /exec 網址；管理部署作業 → 編輯 → 版本選「新版本」 則是把既有部署更新到新程式碼、網址不變。

正確做法是後者：第一次用「新增部署作業」拿到網址、填進 blog；之後每次改程式，都用「管理部署作業」更新同一個部署。如果每次都「新增部署作業」，會不斷產生新網址，而 blog 裡填的還是舊網址、指向舊版本的程式，於是「我明明改了程式怎麼沒生效」。記住這條分工，就避開了這個常見的假故障。

首次授權與未驗證警告

第一次部署（或第一次執行會存取你資料的程式）時，Google 會要求授權，流程中會出現一個「Google 尚未驗證這個應用程式」的警告畫面。這個警告是正常的：它出現的原因是這支腳本是你自己寫的、沒有經過 Google 的應用程式審核，而不是因為程式有問題。走「進階 → 前往（專案名稱）」繼續、再「允許」授予它存取你試算表的權限，就完成授權。

授權授予的範圍只涵蓋程式實際用到的服務（這個案例是那一張試算表），不會給到你其他的 Google 資料。之後這支 web app 以你的身分執行，能做的事就是 doPost 裡寫的那些。

下一步

部署模型清楚後，就能把接收端實際做出來、部署、收到第一筆瀏覽——見模組二：接收端 handler。部署設定「誰可以存取」的安全含義，見模組五。

免費額度該看併發，不看總量

Google Apps Script 對個人（gmail.com）帳號的關鍵限制有這幾條：

對一個接住 beacon、寫一筆進 Sheet 的膠水層，binding 的限制是同時併發 30。這條線的意思是：只要不是在同一瞬間有超過 30 個人的瀏覽器同時打 beacon 進來，就不會撞牆。一篇文章一天被看一千次、但這一千次分散在整天，任何瞬間的併發都遠低於 30，完全沒問題。會出事的情境是「某篇文章上了熱門、一分鐘湧入幾百個瀏覽」——這時併發才可能逼近 30，多出來的請求會拿到錯誤。

值得注意的是，Google 並沒有為個人帳號的 web app 每日呼叫次數公布一個硬性數字，所以正確的估算方式不是去湊「一天幾次」，而是問「我的流量會不會在某個瞬間有 30 個以上的同時請求」。對個人 blog，答案幾乎都是不會。

Apps Script vs Cloudflare Workers 的適用邊界

Apps Script 跟 Cloudflare Workers 都能當免費膠水層接住 beacon，但它們補的場景不一樣。選錯不會壞，但會讓你在錯的地方費力。

Apps Script 適合資料量小、需要人直接讀寫試算表的場景。 它最大的優勢是 Google Sheet 同時是儲存體跟儀表板——資料一 append 進去，你打開試算表就能看、能排序、能畫圖、能用樞紐分析，不必另外做前端。起步不需要信用卡、不需要買 domain、不需要學部署工具。代價是效能：每次執行有冷啟動延遲，Sheets 當資料庫在資料列數很多時讀寫會變慢，併發上限只有 30。對「一個人的 blog 想知道哪篇有人看」，這些代價都碰不到。

Cloudflare Workers 適合量體較大、需要低延遲的場景。 免費方案給到每天十萬次請求量級，冷啟動幾乎感覺不到，全球邊緣節點讓 beacon 延遲很低。代價是它沒有內建的試算表 UI——資料要存進搭配的 KV 或 D1（免費的 SQLite），看資料得自己寫查詢或做一個小前端。它更接近「一段真的後端程式」，彈性大但要自己搭的部分多。

選型判準用一句話收斂：先問資料要不要讓人打開試算表直接看、量會不會大到讓 Sheets 變慢。 想要試算表即儀表板、量不大——Apps Script。要低延遲或預期量大、能接受自己搭查詢介面——Workers。本指南先走 Apps Script，因為它把「看資料」這件事直接解決了，最適合第一次做流量統計、想快點看到成果的人。模組五會給出「Sheets 開始撐不住時怎麼判斷、怎麼往 Workers 遷移」的訊號與路徑。

自建與現成分析服務的差異

前面比較的兩個選項都是「自己搭」。在動手之前值得先看一眼另一條路：Google Analytics、Plausible、Umami、GoatCounter 這類現成服務同樣是貼一段 JS 就開始收資料，而且不必自己處理接收端、儲存、退出機制與資料判讀。

能力上的差異比想像中小。這些服務與自建同樣受只看得到執行 JavaScript 的訪客這條限制，也同樣會被廣告與隱私擴充功能攔截——它們的網域出現在攔截清單上的機率甚至更高。真正的差別在三個地方：

資料的所在位置。 自建的資料在自己的試算表裡，想怎麼查就怎麼查、要保留多久就保留多久；託管服務的資料在對方的系統裡，導出格式與保留期限由對方決定。

要處理的工作量。 退出機制、欄位變更同步、判讀規則的維護在自建這側全部要自己做，這些工作在模組六佔的篇幅比 beacon 本身還多。託管服務把這些都包好了。

理解的深度。 自己做過一次之後，「這個數字是怎麼來的、它漏掉了什麼」變成可以回答的問題。用託管服務時那些答案在對方的文件裡，而多數人不會去讀。

判準因此是：想搞懂這套機制怎麼運作、或者資料必須在自己手上——自建。只想知道哪幾篇比較多人看——現成服務省下的工作比預期多，本指南反而是拿來理解它們在做什麼的參考。

下一步

工具選定 Apps Script 後，先搞懂它的部署模型跟授權模型，才不會在模組二實作時卡在「為什麼我的網址打不通」。往模組一：Apps Script 地基。

onFormSubmit：表單提交即時處理

Google 表單本身會把回應存進一張試算表，但「存進去之後要做什麼」需要 Apps Script。onFormSubmit 觸發器在每次有人提交表單時執行，拿得到這次提交的內容：

1function onFormSubmit(e) {
2  var answers = e.namedValues;        // { "Email": ["a@b.com"], "問題": ["內容"] }
3  // 例如：寄一封通知信給自己
4  MailApp.sendEmail("you@gmail.com", "新表單回應", JSON.stringify(answers));
5}

這讓表單從「被動收集」變成「即時反應」——提交當下就寄通知、寫進別的表、或呼叫外部 API。對 blog 的延伸應用，例如做一個「訂閱通知」或「回饋表單」，onFormSubmit 是接手處理的入口。要注意 MailApp.sendEmail 受每日寄信配額約束（個人帳號每天 100 封收件人，見執行配額），高頻通知要留意。

onEdit：試算表被編輯

onEdit 在試算表任何一格被改動時觸發，拿得到改了哪一格、新值是什麼。它適合「維護試算表內部的衍生狀態」，例如某欄被填值時自動在旁邊算出對應結果。對流量統計這條主線用得不多，但它是 Sheets 自動化的常見工具，值得知道它存在。

simple 與 installable：一個權限分界

事件觸發器有兩種形式，差別在能不能做需要授權的事，這是容易踩的分界。

Simple 觸發器是靠函式命名約定自動生效的：把函式命名為 onOpen、onEdit 這些保留名字，不必註冊就會在對應事件觸發。代價是它跑在受限環境裡——不能做需要授權的操作，例如寄信、呼叫外部 URL、存取其他檔案。它適合純粹在當前檔案內、不碰外部的輕量反應。

Installable 觸發器是明確註冊的（用 ScriptApp.newTrigger(...).forSpreadsheet(...).onEdit().create()，或在觸發條件介面建立），它以你的授權身分執行，能做需要權限的操作（寄信、UrlFetch、跨檔案）。onFormSubmit 要做寄信這類事，必須是 installable 的。

判準很直接：這個事件處理要不要碰當前檔案以外的東西——不要（只在表內算個值），simple 夠用；要（寄信、打 API、寫別的表），得用 installable。踩雷的典型情境是「我寫了一個 onFormSubmit 想寄通知信，怎麼都沒寄出」——因為它被當成 simple 觸發器、而 simple 不能寄信；改成明確註冊的 installable 就好。

下一步

觸發器（時間的與事件的）把統計從「手動查」變成「自動跑」。整套統計上線後怎麼守住配額、擋濫用、保持資料乾淨，見模組五：部署、配額與安全。

配額實際碰撞會怎樣

免費配額的三條線（單次 6 分鐘、同時併發 30、觸發器每日 90 分鐘，見執行配額）在正常個人 blog 幾乎碰不到，但知道碰到時的症狀有助於診斷。

同時併發 30 是接收 beacon 最可能先碰的線：某篇文章瞬間爆紅、一秒內湧入超過 30 個瀏覽，第 31 個以後的 doPost 會拿到錯誤、那幾筆瀏覽漏記。症狀是「爆量時段的統計數字明顯偏低」。單次 6 分鐘 接 beacon 用不到（寫一列幾百毫秒），但彙總 trigger 全表掃描在資料很多時會逼近，症狀是彙總 trigger 開始逾時失敗。每日 90 分鐘 是所有觸發器加總，正常一天彙總一次遠遠用不完，除非彙總寫得很沒效率或觸發器被重複註冊。

碰到併發上限的處理不是「調高配額」（個人帳號調不了），而是「削峰」——beacon 本來就是可容忍少量遺失的統計，爆量漏記幾筆不影響「哪篇熱門」的判斷；真的很在意，訊號就指向遷移到吞吐更高的 Workers。

濫用防護與資料乾淨度

公開端點的騷擾型風險（髒資料、配額消耗，見部署與存取權限），對應兩個層級的防護。

過濾自己的瀏覽是最先該做、報酬最高的一項——不是防外人，是防站主把開發與自我瀏覽混進統計。前端的 hostname guard 已經擋掉本機預覽（見前端 beacon）；要進一步排除「在正式站上自己一直重整」，可以在瀏覽器存一個退出標記、beacon 讀到就不送，或彙總時依訪客識別碼過濾。兩者的取捨在於前者省下配額與列數、後者保留資料可回頭校正，而它們可以並用。退出標記的實作、邊界與各瀏覽器的差異見訪客識別與 opt-out——存標記的版本同時也是給讀者的退出入口，適合公開在網站說明裡。

擋隨手亂打用一個約定 token：前端 payload 放一個固定字串、doPost 檢查對不上就丟掉不寫。這能擋掉不知情的爬蟲與隨手 POST，成本很低。但要誠實看待它的邊界：token 也在 client JS 裡看得到，鐵了心要灌的人抓一下原始碼就有——所以 token 是「擋雜訊」不是「擋攻擊」。對個人 blog，擋雜訊通常就夠了；真的被針對性灌爆，那是遷移到有更多防護手段（rate limiting、驗證）的平台的訊號。

隱私與 PII 邊界

這套統計在隱私上的立足點是根本不收集個人身分資訊，這讓它天然乾淨。具體有三條線值得明確守住：

• 不記 IP：Apps Script 的 web app 收不到訪客 IP，所以就算想記也記不到——這反而是好事，少一個 PII 來源。
• 裝置只送粗標籤：mobile / tablet / desktop 三選一足以回答「用什麼裝置看」，不送完整 userAgent（那帶版本等可組成瀏覽器指紋的細節）。
• 不放可識別個人的欄位：這一章講到的 payload 只有路徑、來源、語言、裝置，沒有任何綁到個人的東西。模組六會加上兩個隨機識別碼——它們同樣不含個人資訊，但確實會被寫進瀏覽器的儲存空間，下一段的同意機制討論就是為此。

不收 PII 讓「處理個資刪除請求」這類負擔不會發生，但同意機制的判斷不是由 PII 決定的。歐盟 ePrivacy 指令第 5(3) 條管的是「在使用者終端設備儲存或讀取資訊」這個動作本身，與存的內容是否為個資無關——市面上宣稱免同意橫幅的分析服務（Plausible、Fathom）之所以能這樣宣稱，正是因為它們完全不在瀏覽器儲存任何識別碼。模組六的訪客識別在 localStorage 存了兩個，因此那一步跨過了這條線。

實務上個人網站的合規風險與商業追蹤網路不在同一個量級，但這是取捨不是豁免。想更保守，可以尊重瀏覽器的 Do Not Track 訊號（navigator.doNotTrack === "1" 時不送 beacon），或者不存識別碼、只做頁面計數。

遷移訊號：什麼時候該離開 Sheets

Apps Script + Sheets 是為「量小、要人直接看試算表」設計的（選型見模組零）。以下訊號累積出現時，代表量已經長到該換更重的工具：

• 爆量時段頻繁撞併發上限、漏記明顯到影響判斷。
• 彙總 trigger 即使分表、只讀增量後仍逼近 6 分鐘。
• raw log 的 cell 數逼近試算表上限（見資料模型與容量邊界）。
• 需要的查詢已經超出試算表能力（多維交叉、即時儀表板）。

遷移的方向是把接收端換成 Cloudflare Workers、儲存換成 D1（免費 SQLite）：吞吐與查詢能力遠高於 Sheets，代價是失去「打開試算表就能看」的便利、要自己做查詢介面。判準用一句話收斂：當「Sheets 即儀表板」的便利已經被它的容量與吞吐限制抵銷，就是遷移的時機——在那之前，簡單版一直是對的選擇。

管線完成之後

到這裡，一套不租主機、資料存在自己試算表裡的流量統計已經建好，而且知道它的配額邊界、防濫用手段與遷移訊號在哪。

管線能跑，不代表資料讀得出意義。 收到的來源網址大量空白、任兩列之間看不出是不是同一個人、真人與機器抓取混在一起——這些問題只在真實流量打進來之後才浮現，處理方式見模組六：收到資料之後。那一章會在 payload 上增加欄位，本章的配額判斷也會因為列數翻倍而需要重算。

想把同一套膠水模式套到別的靜態站或別的工具，回模組零的選型重新判斷即可。

準備一張 Sheet 當儲存體

先在 Google Sheets 建一張新試算表，命名例如 blog-analytics。第一列放欄位標題，對應接收端要寫的欄位：時間、路徑、來源、語言、裝置。這一列標題只是給人看的，接收端從第二列開始 append 資料。

Apps Script 有兩種綁定方式，這裡用容器綁定：直接在這張試算表的選單開 擴充功能 → Apps Script，開出來的 script 專案天生就跟這張試算表綁在一起，程式裡用 SpreadsheetApp.getActiveSpreadsheet() 就能拿到它，不必記試算表 ID。兩種綁定方式的差異、以及什麼時候該用獨立專案，見模組一：Apps Script 地基。

寫 doPost 接住 beacon

前端用 sendBeacon 送 POST，所以接收端要實作 doPost。sendBeacon 送來的內容放在 e.postData.contents，是一個 JSON 字串（前端刻意用 text/plain 傳輸、內容仍是 JSON），接收端 JSON.parse 把它還原：

 1function doPost(e) {
 2  try {
 3    var data = JSON.parse(e.postData.contents);
 4
 5    var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("工作表1");
 6    sheet.appendRow([
 7      new Date(),          // 時間：用伺服器時間，不信任前端傳的時間
 8      data.path || "",     // 路徑
 9      data.ref || "",      // 來源
10      data.lang || "",     // 語言
11      data.dev || "",      // 裝置：mobile / tablet / desktop
12    ]);
13
14    return ContentService
15      .createTextOutput(JSON.stringify({ ok: true }))
16      .setMimeType(ContentService.MimeType.JSON);
17  } catch (err) {
18    return ContentService
19      .createTextOutput(JSON.stringify({ ok: false, error: String(err) }))
20      .setMimeType(ContentService.MimeType.JSON);
21  }
22}

三個實作決定值得說明：

時間用伺服器的 new Date()，不用前端傳的時間。 前端時間來自使用者的裝置，時區、時鐘準不準都不可控，還多一個可被偽造的欄位。接收端執行的當下時間就是最接近真實的瀏覽時間，用它最乾淨。這也是前端 payload 不需要送時間戳的原因。

每個欄位都用 || "" 給預設值。 beacon 有可能因為前端狀況送來缺欄位的資料，data.path 若是 undefined，直接寫進 Sheet 會是空格但不會報錯；用 || "" 明確寫成空字串，讓資料形狀一致，之後彙總不會踩到 undefined。

整段包在 try/catch 裡。 接收端可能收到格式壞掉的請求（爬蟲亂打、payload 不是合法 JSON）。JSON.parse 遇到壞資料會丟例外，沒接住的話這次執行算失敗、也可能讓錯誤累積。包起來後，壞請求就回一個 ok: false、不影響服務。真正在意這些壞請求要不要防、怎麼防，見模組五。

回應用 ContentService.createTextOutput 回一小段 JSON。sendBeacon 是 fire-and-forget、前端根本不會讀這個回應，所以回什麼不重要——但 doPost 必須回一個 ContentService 的輸出，這是 Apps Script web app 的硬性要求，不回會被當成執行沒有正常結束。

部署成 web app

程式寫好還打不通，因為它還沒有對外網址。在 Apps Script 編輯器右上角 部署 → 新增部署作業，類型選 網頁應用程式，兩個設定要對：

• 執行身分（Execute as）：選「我」。beacon 是匿名訪客送來的，他們沒有你試算表的權限；選「我」讓這段程式用你的身分執行，才寫得進你的 Sheet。
• 誰可存取（Who has access）：選「所有人」。訪客是沒登入 Google 的匿名瀏覽器，只有「所有人」這個選項能讓匿名 beacon 打得進來。

部署後會拿到一個網址，形如 https://script.google.com/macros/s/AKfyc.../exec。把這個網址填回前端 beacon 的 ENDPOINT（見前端那半）。這兩個設定的安全含義——「所有人可存取」會不會被濫用、要不要加保護——在模組五完整討論；先讓它通，才有東西可以保護。

確認收到第一筆

部署完、前端網址也填好後，打開你的 blog 任一頁（正式網域，不是本機預覽），beacon 就會送出。回到 Google Sheet，第二列應該出現一筆：伺服器時間、你剛看的路徑、來源、語言。看到這一列，整條 client beacon 管線就打通了——前端偵測、跨網域送達、接收端解析、寫進儲存體，每一環都在運作。

如果沒出現，最常見的兩個原因：一是前端 ENDPOINT 填成舊的部署網址（每次「新增部署作業」網址會變，改程式後要用「管理部署作業」更新同一個部署、網址才不變），二是部署的存取權限沒設成「所有人」導致匿名 beacon 被擋。這兩個都是設定問題，不是程式問題。

下一步

第一筆進來了，往下有兩條路。

想知道這些資料怎麼讀出意義——來源網址為什麼大量空白、怎麼判斷兩列是不是同一個人、哪些是機器抓取——走模組六：收到資料之後。那一章會在 payload 上增加欄位，屆時這裡的 appendRow 與試算表的表頭要跟著改，改法在該章的欄位變更清單。

想先把儲存層打穩——多個瀏覽在同一瞬間打進來時 appendRow 會不會互相覆蓋、資料列累積到幾萬列時 Sheets 還撐不撐得住——走模組三：Sheets 當資料庫。

Apps Script 是 Google 托管的 JavaScript 執行環境，跑在 V8 runtime 上，對個人帳號免費。它跟一般伺服器最大的差別是沒有一台常駐主機——程式只在被呼叫時執行、跑完就休眠，你不必管作業系統、不必管開機關機、不必付閒置費用。代價是它有執行時間與併發上限（見模組零：免費額度的思考方式）。

章節文章

跨分類引用

• → 模組零：免費額度的思考方式與工具選型：為什麼選 Apps Script
• → 模組二：流量 beacon 實作：把地基用在實作上

這一章的作法受兩個限制支配：接收端拿不到判別素材，以及會出現在這份統計裡的機器比想像中少。先講清楚這兩件事，它們決定了訊號從哪裡來、以及能期待抓到什麼。

接收端讀不到請求標頭

Apps Script 的 doPost(e) 事件物件提供 parameter、parameters、queryString、contentLength、postData、pathInfo 這幾個欄位，不提供任何 HTTP 標頭。這代表接收端拿不到 User-Agent，也拿不到來源 IP。

傳統的伺服器端過濾（比對 UA 字串、查 IP 反解、比對已知爬蟲的 IP 區段）在這個架構下全部不可用。所有判斷素材必須由前端蒐集之後放進 payload 送出——這既是限制，也界定了設計空間：能用的訊號只有瀏覽器環境暴露給 JavaScript 的那些。

這個限制連帶產生一條必須守住的界線。前端能取得完整的 userAgent、螢幕尺寸、時區、字型清單，把它們全部送出確實能提高辨識率，但那正好構成瀏覽器指紋——為了分辨機器而蒐集足以識別個人的資料，取捨方向是錯的。後面的每個訊號都在「有判別力」與「不構成指紋」之間取值。

會被 beacon 記錄到的機器只有一小部分

beacon 靠 JavaScript 觸發，所以只有會執行 JS 的抓取工具才會進入這份統計。這一條大幅縮小要辨識的對象範圍，而它與直覺相反：

AI 訓練爬蟲不執行 JavaScript 是其中最反直覺的一項。Vercel 在 2025 年對自家平台流量的量測顯示，GPTBot 與 ClaudeBot 都會抓取 JS 檔案卻從不執行；連結預覽服務只讀 HTML 的 meta 標籤。在主流爬蟲裡，目前已知具備完整 JS 渲染的只有 Googlebot——這是對演化中的世界所做的觀察，不是永久成立的分類，各家的渲染能力隨時可能改變。

這件事有三個後續影響。其一，這套統計看不見的機器流量遠多於看得見的——伺服器日誌裡的爬蟲比例與這裡的數字不可比較。其二，下一節那份具名清單接住的是「會執行 JS」與「誠實申報身分」的交集，比清單本身小得多；清單裡多數條目預期永遠不會命中，保留它們是為了接住少數會渲染的變體。

其三會影響上一章的判讀：來源網址空白的成因把「自動化抓取」列為其中一類，而這一節說明了那一類的實際佔比比直覺低——真正大量抓取的工具不執行 JS、根本不在這份資料裡。空白列偏向真人的機率因此比乍看之下高。

訊號分層與信心度

四個訊號的可靠度不同，分開記錄而不是合併成單一結論。

這個信心排序由誤差方向推導而來，不是本站資料測得的命中率。 沒有標註任何誤判比例是刻意的——那需要一份已知組成的對照流量，而本文的每個判準都停在「這個訊號可能怎麼錯」的層次。既然正確率無從得知，處置方式就不是「先用著、之後校正」，而是讓判定與使用分離：訊號照實記下、判定留在彙總端，改了規則之後可以拿同一批舊資料重跑比對。

navigator.webdriver 是自動化框架的預設標記。 Playwright、Puppeteer、Selenium 啟動的瀏覽器這個值都是 true，一般瀏覽器是 false。它的判別力強而誤判極少，代價是刻意規避偵測的工具第一件事就是把它蓋掉——因此它抓得到的是「沒有隱藏身分意圖」的自動化訪客。

UA 比對抓的是自我申報。 搜尋引擎與正派的抓取服務會在 User-Agent 裡寫明自己是誰，這是它們與網站經營者之間的慣例。比對這個字樣不會誤判真人，因為真人的瀏覽器不會自稱是機器。

空語言清單與零視窗尺寸原本是無頭環境的特徵，而這兩條正在失效。 Chrome 112 起的新無頭模式會建立一個不顯示的平台視窗，並帶有正常的語言偏好，兩項特徵大多不再成立。它們的誤差方向因此從「誤判真人」偏向「漏判機器」——保留是因為舊版工具仍在使用中，但不能當作主力。

因為誤差方向不同，記錄下來的是命中了哪些訊號、而不是一個布林結論：

 1function botSignal() {
 2  var hits = [];
 3  try {
 4    if (navigator.webdriver === true) hits.push("webdriver");
 5    // UA 比對見下一節
 6    if (!navigator.languages || navigator.languages.length === 0) hits.push("lang");
 7    if (!window.outerWidth || !window.outerHeight) hits.push("size");
 8  } catch (err) {
 9    // 偵測本身出錯不該影響統計，當作沒有訊號
10  }
11  return hits.join(",");
12}

這個設計讓判定閾值留在彙總端——也就是試算表那一側，資料寫進去之後用公式分類的地方。日後發現某條訊號誤判太多，改公式就好，不必改前端重新部署；而前端一旦部署出去，快取的頁面還會用舊版跑一段時間。

送出的字串寫進試算表的一個欄位，後面稱它為訊號欄。

具名比對與通用退回

UA 比對要回答的問題有兩層：「這是不是機器」以及「是哪一隻機器」。後者的價值在於處置方向不同——搜尋引擎索引是內容被收錄的證據，監控服務是自己設定的，而不具名的抓取工具才是需要留意的那一類。

直覺的作法是列一份已知名單做精確比對。這個作法單獨使用時有一個不會顯現的失效模式：名單會過時，而過時的表現是新出現的抓取工具完全不被標記——統計上呈現為自動化流量比例逐漸下降，而這個下降與「內容吸引到更多真人」在數字上不可區分。

因此比對分成兩層，讓過時的代價落在精度而非覆蓋：

 1// 以下兩個常數與比對邏輯接在上一段 botSignal() 的 try 區塊內，共用同一個 hits 陣列
 2// 已知抓取工具的自我申報名稱，命中時送出具體名稱
 3var KNOWN_BOTS = /claudebot|claude-user|claude-searchbot|gptbot|oai-searchbot|chatgpt-user|perplexitybot|googlebot|bingbot|applebot|duckduckbot|yandexbot|bytespider|amazonbot|ccbot|meta-externalagent|facebookexternalhit|twitterbot|linkedinbot|slackbot|discordbot|telegrambot|whatsapp|semrushbot|ahrefsbot|dotbot|petalbot/i;
 4// 通用字樣，接住誠實申報但不在具名清單裡的自動化訪客
 5var GENERIC_BOT = /bot\b|crawler|spider|headless|slurp|bingpreview|python-requests|curl\//i;
 6
 7var ua = navigator.userAgent || "";
 8var named = ua.match(KNOWN_BOTS);
 9var generic = named ? null : ua.match(GENERIC_BOT);
10if (named) hits.push("ua:" + named[0].toLowerCase());
11else if (generic) hits.push("ua:" + generic[0].toLowerCase().replace(/[^a-z]+$/, ""));

兩層的比對來源不同是關鍵：具名層比對的是身分（清單裡的名字），通用層匹配的是類別詞（bot、crawler、spider、headless），後者不需要知道任何一隻抓取工具的名字就能運作。清單過時時，新工具仍然被通用層接住——失去的是「知道是誰」，不是「知道有」。

上面的 GENERIC_BOT 裡混了 slurp、bingpreview、python-requests、curl/ 四個具體名稱，嚴格說它們屬於具名層——把產品名放進退回層，退回層就變成清單的延伸而不是獨立的一層。實際運作上它們是無害的殘留，但這個混用會讓「通用層純靠類別詞」這個保證打折：wget、Go-http-client、node-fetch、axios 這些同樣不含類別詞的 UA，兩層都接不住。

真正獨立於 UA 的那一層是 webdriver / lang / size ——它們讀的是瀏覽器環境而非字串，UA 比對整個失效時仍然運作。三層的關係值得明說：具名層給身分、通用層給類別、環境訊號層給「這個執行環境不像人用的」，而只有第三層完全不依賴任何列舉。

這個結構要能被觀測，標記本身得分得出層級。上面的寫法送出的是 ua:googlebot 與 ua:bot，而 ua:slurp 這種看起來像具名層、其實來自通用層——不比對兩條 regex 就分不出來。加一個前綴讓它自證：

1if (named) hits.push("ua:named:" + named[0].toLowerCase());
2else if (generic) hits.push("ua:generic:" + generic[0].toLowerCase().replace(/[^a-z]+$/, ""));

分得出層級之後，COUNTIF(訊號欄, "*ua:generic*") / COUNTIF(訊號欄, "*ua:*") 就是清單的過時指標：這個比例上升代表有新工具在被通用層接住、該更新具名清單了。這把「清單過時」從一件不可見的事變成一個可以看的數字，而且不需要有人事先知道漏了哪些新工具。抽象層的原則見 #251 清單過時的代價要落在精度、不落在覆蓋。

清單維護有一個實際邊界值得先講明。Anthropic 目前把不同用途拆成 ClaudeBot、Claude-User、Claude-SearchBot 多個 token，這類拆分會持續發生，而拆分後的新名稱在被加進清單前由通用層接住——那正是這個設計在運作。

另一個邊界是命名系統的混淆，而這份清單踩過一次。它上線時含有 google-extended 這個條目——那其實是 robots.txt 的控制 token，不會出現在任何請求的 User-Agent 裡，因此它從第一天起就是死的。系統不會回報「某個條目從未命中」，這個缺陷是靠一次外部查核才浮現的。robots.txt 的控制 token 與 UA 字串是兩套獨立的命名，這正是「訊號只能來自瀏覽器暴露給 JavaScript 的東西」這條限制的具體案例。

只送出命中的關鍵字、不送完整 userAgent，是前面那條界線的具體落實——那個關鍵字是抓取工具主動公開申報的身分，不構成指紋特徵。

行為訊號對沒有規避意圖的工具有效，代價是誤判方向指向真人

行為留下的痕跡比環境屬性稍微難改，但它們擋不住有規避意圖的工具。前面對 webdriver 說過的那句讓步在這裡同樣適用，而且成本更低：讓抓取工具在關閉前觸發一次 visibilitychange 是三行程式碼，隨機化頁面存活時間是一行，重用瀏覽器的 storage state 讓識別碼保持穩定是兩行——最後這項甚至提升效率，因為它本來就是自動化測試處理登入狀態的標準做法。

這一節的三個訊號在對象沒有隱藏意圖時判別力最強，同時誤判代價也最高——誤差方向一致指向「把真人判成機器」，而這個方向最難察覺，因為結果看起來是流量變乾淨了。

離開事件缺席是其中最直接的一個。抓取工具取得頁面內容後直接終止瀏覽器環境，不會經歷「頁面轉為不可見」這個狀態轉換，因此不產生離開事件。

真人這一側同樣會缺席，而且不罕見。事件模型列過那份丟失清單：記憶體回收、強制關閉、斷電、網路中斷、擴充功能攔截、接收端併發撞頂。行動流量佔比高的站，真人的離開事件缺席率本來就不低，把缺席直接當成機器訊號會系統性誤判這一群人。

只有離開事件、沒有進入事件這個相反的形態也一樣。可觀測的只有一件事：接收端在進入事件的時間點沒有收到任何請求。抓取工具的網路攔截設定是一種相容的成因——許多框架只放行文件與必要資源，等內容抓完、進入關閉流程時攔截器已經解除——但它只是幾個候選之一。

真人也會產生孤兒離開事件，至少三條路徑：接收端併發撞頂（執行配額的併發上限，見模組五的配額碰撞——爆量時同時湧入的進入事件被拒，離開事件數秒後送達時併發已消退，正好剩下孤兒）、廣告或隱私擴充功能攔截第一次請求、以及網路瞬斷。第一條特別值得注意，因為它與爆量時段重疊，會把流量高峰的真人整批劃給機器。

停留時間的一致性洩漏的是排程。抓取工具的頁面存活時間由設定決定，因此相隔數小時、來自不同識別碼的多列可能有精確相同的秒數。這一條需要區間限定：dur 經過取整為秒，而真人的跳出流量集中在最短的那幾秒，在那個區間裡精確重複是常態而非訊號。分界落在哪一秒由下一節的短停留分佈量出來，不是一個可以跨站沿用的固定值。只有落在跳出區間之外的精確重複才有判別力。

三個訊號各自的觀察都只有個位數的記錄撐著，所以它們指出的是「該往哪裡看」，不是「這一列是什麼」。

先量本站的基線

前面所有訊號都描述「機器可能長什麼樣」，而判定需要的是「這一列與本站的真人有多不一樣」。判準寫成絕對條件（缺席、為零、幾乎沒有）在換一個站之後就不成立：行動流量佔八成的站與桌機為主的站，真人的離開事件缺席率差距很大；剛上線五篇文章的站，真人的站內導覽比例天然接近零。

基線要用一批組成已知的流量來量，而唯一穩定可得的那批是自己的瀏覽：在設定 opt-out 之前刻意走幾條完整的閱讀路線，那批記錄裡每一列是誰產生的都確定。

第三欄不是免責聲明，它決定判讀的方向：站內來源比例的基線偏高，代表真實讀者低於這個值是正常的，拿它當「低於就可疑」的門檻會系統性誤判。四個指標的偏差方向都指向同一側——真人看起來比基線「差」。

有一種量法要避開：用「訊號欄乾淨」的記錄當已知樣本。那等於用被校正的偵測器定義校正用的樣本，結論會自我印證。同理，量離開事件缺席率時不能只取互動旗標為 1 的記錄——那個條件蘊含離開事件已經送達，算出來必然是零。

樣本規模也要誠實看待：刻意走幾條路線得到的是數十列，那個量足以看出量級差異（缺席率是一成還是六成），不足以做統計顯著性判斷。判準因此寫成「明顯偏離基線的量級」而非某個百分點門檻。

基線本身要重量：改版換了頁面結構、流量來源組成變化、行動裝置佔比上升，都會讓它漂移。

這一節的限制會累積到哪裡

前面每一節都交代了自己的限制：只有執行 JavaScript 的訪客會被記錄、離開事件會在幾種情境下丟失、訊號的誤差方向一致指向誤判真人。這些限制加上其他篇的（退出機制、配額漏記、儲存清除）共同界定了這份資料的母體，而母體決定了哪些結論下得出來——完整的總帳與外部對照方法見這份統計的分母是什麼。

標記而非丟棄

偵測到疑似自動化流量時有兩種處置：前端直接不送，或照常記錄並加上標記欄位。

這一章從頭到尾談的是標記，不是阻擋。靜態站託管層沒有可以攔請求的地方，這些訊號只在資料進來之後才產生作用——真的要擋抓取工具需要 CDN 或反向代理層的規則，那是另一個主題。

照常記錄買到的是三件不需要 ground truth 的事。 判定的正確率本身無從得知——這套統計沒有一份標好答案的對照資料，前面每個訊號都只能談誤差方向、談不了誤判率。真正的理由在別處：

改了規則之後可以重跑舊資料，比對同一批記錄在新舊規則下的分佈差多少。這回答不了「哪一個對」，但看得出「改動影響了多少列」，而那是決定要不要改的實際依據。

日後認出新的抓取工具時可以回溯標記。今天標成 ua:bot 的那些列，等它被加進具名清單之後仍在表裡，過去半年的歷史因此跟著變得可讀。丟掉的列沒有這個機會。

總量守恆檢查的前提就是列沒有被丟掉。前端過濾會讓分母本身失真，而分母失真時所有比例都不可信。

代價是試算表多存一些列，以及彙總時必須記得過濾。

對免費配額敏感、或流量大到列數成為問題時，取捨會反過來——那時應該只丟棄高信心訊號（webdriver 與具名 UA）命中的部分，中信心與行為訊號仍然照常記錄。

彙總端的分類與條件順序

分類邏輯把訊號與行為組合起來。以下是虛擬碼——欄位名要換成試算表的實際範圍參照，而每個閾值都該換成前面量出的基線值，寫成固定條件只是為了讓結構清楚：

1=IFS(
2  AND(事件="leave", 同session同路徑的view筆數=0), "待查-孤兒離開事件",
3  事件<>"view", "",
4  REGEXMATCH(訊號欄, "webdriver|ua"), "機器-高信心",
5  AND(同session的leave筆數=0, 裝置<>"mobile"), "待查-無離開事件",
6  訊號欄<>"", "訊號弱-待觀察",
7  同session的view筆數=1, "單頁即走",
8  AND(同session的leave筆數>0, 訊號欄=""), "真人",
9  TRUE, "未分類")

條件的順序承載語意。孤兒離開事件排在最前面，否則第二條會把所有離開事件留白，那一整類記錄就在統計裡消失了。非進入事件留白避免同一次瀏覽被計數兩次。

分類名稱用「待查」而非「爬蟲」是刻意的：行為訊號給的是需要進一步確認的候選。孤兒離開事件要對照執行項目同時段有沒有失敗紀錄——有的話那是配額問題而非機器。無離開事件那一條排除了行動裝置，因為真人在該環境的缺席率本來就高。

最後兩條分支的分工是刻意的。「真人」寫成顯式條件、catch-all 標成「未分類」，而不是反過來讓沒被接住的列直接落進「真人」——後者是這份報表最被消費、最不會被追問的類別，新的資料形狀靜默落進去只會讓數字變好看。IFS 在所有條件都不成立時回傳 #N/A，而滿欄的錯誤值與滿欄的留白一樣不會被追問，所以 catch-all 要給一個會被看見的標籤。這條防線的完整推導見假故障與靜默失效的診斷。

用總量守恆檢查這份分類時，作用域是進入事件那些列——離開事件被第二條留白，把它們算進分母會讓差額永遠等於離開事件的列數，而一個恆常的巨大差額只會訓練出忽略它的習慣。

下一步

判定規則到位了，接下來要問的是這些規則吃進去的資料本身可不可信。判定寫對了但公式算錯、程式改了但端點沒生效、錯誤訊息指向的位置不是問題的位置——假故障與靜默失效的診斷處理這三類。

爆量時段的漏記是另一回事，它來自配額而非判定，見模組五的配額、防濫用與隱私邊界。

概念位置

事件物件只帶請求的內容，不帶任何 HTTP 標頭——User-Agent 與來源 IP 在這裡都讀不到。伺服器端常見的 UA 比對與 IP 判斷因此不可用，需要那些資訊時只能由前端蒐集後放進請求主體送來（見辨識自動化流量）。

兩個函式都必須回傳一個 ContentService 或 HtmlService 的輸出，這是平台的硬性要求；不回傳會被當成執行沒有正常結束。接收 beacon 這類「送資料進來」的場景用 doPost，因為 sendBeacon 送的是 POST，主體放在 e.postData.contents（是個字串，需要自己 JSON.parse）。

可觀察訊號與例子

一個影響靜態站的關鍵限制是：Apps Script 沒有 doOptions。跨網域請求的 CORS preflight 會送 OPTIONS，但它打不到你的程式、平台的預設回應也不帶 CORS 許可標頭，於是 preflight 失敗、真正的請求送不出去。

判讀方式

這是「用 fetch 送 application/json 打 Apps Script 得到 CORS 錯誤」的根因，繞法是讓請求成為不觸發 preflight 的 simple request，見前端 beacon 與 CORS 障礙。

實作拆成兩半，剛好對應架構的兩端。前端這半的重點是用對送出方式，避開靜態站打 Apps Script 最常見的 CORS 障礙。接收端這半的重點是把請求解析出來、安全地 append 進試算表。

章節文章

跨分類引用

• → 模組一：Apps Script 地基：doGet/doPost 與部署模型的完整說明
• → 模組三：Sheets 當資料庫：資料進來後的並發、資料模型與容量
• → 模組六：收到資料之後：這裡的 payload 只描述單次瀏覽，補上訪客識別、停留時間與自動化訊號之後才讀得出「幾個人來過、有沒有真的在讀」

概念位置

觸發器的 90 分鐘每日總時間是另一條線，影響的是時間觸發器做的排程彙總，不是接收 beacon。

可觀察訊號與例子

估算容量時該看的是併發而非總量。接收 beacon 的膠水層，每次執行只寫一筆、幾百毫秒結束，遠用不到 6 分鐘；binding 的限制是「同一瞬間最多 30 個 beacon 在處理」。個人 blog 的流量分散在整天、任何瞬間的併發都遠低於 30，所以不會撞牆；會逼近上限的是「某篇文章短時間爆量」這種尖峰。

判讀方式

值得注意的是個人帳號的配額比 Google Workspace 帳號低，所以同一段程式在測試帳號能過、在別的帳號可能撞限。碰到配額上限的處理見模組五。

這套統計的執行環境被切成四段——頁面上的 JavaScript、Apps Script 的部署層、接收端程式碼、Google 試算表——而每一段的狀態各自獨立。任何一段沒跟上都不會產生跨段的錯誤訊號，這是免伺服器架構特別容易產生假故障的結構原因。

錯誤訊息指向的位置不是問題的位置

Google 服務類別的查詢方法在找不到目標時回傳 null，而不是拋出例外。錯誤因此延後到使用回傳值的那一刻才發生：

1function inspectHeaders() {
2  var sheet = SpreadsheetApp.getActive().getSheetByName('log');
3  var lastCol = sheet.getLastColumn();   // TypeError: Cannot read properties of null
4}

訊息指向 getLastColumn，而真正的問題在上一行——這個試算表裡沒有名為 log 的工作表。判讀規則是：訊息形如「無法讀取 null 的某屬性」時，問題在產生那個 null 的地方，不在使用它的地方。

診斷方式是把假設換成觀測：先列出實際存在的工作表，再對照程式碼裡寫的名稱。

1function listSheets() {
2  SpreadsheetApp.getActive().getSheets().forEach(function (sheet) {
3    var lastCol = sheet.getLastColumn();
4    Logger.log('工作表「%s」 欄數=%s 列數=%s', sheet.getName(), lastCol, sheet.getLastRow());
5  });
6}

這段程式碼的價值在於它不帶任何關於名稱的假設。同樣的模式適用於所有「用名稱或 ID 取得物件」的 API——先列出實際存在的東西，再對照程式碼裡寫的。

有一個延伸判讀值得記住：getActive() 回傳的是這個 Apps Script 專案所綁定的試算表。專案綁在 A 表、而資料寫進 B 表（透過 openById）是完全合法的配置，這時 getActive() 拿到的是 A 表。工作表名稱與欄位都對不上時，要先確認取得試算表的方式，再懷疑工作表名稱。

程式改了但端點沒生效

Apps Script 把「編輯器裡的程式碼」與「端點服務的版本」設計成兩個獨立狀態。手動執行函式跑的是前者，HTTP 請求打到的是後者——這代表「我執行某個函式成功了」與「端點跑的是新版」是兩件事，前者成立不推出後者。

這個設計本身是合理的版本控制：可以邊改程式碼邊讓線上端點維持穩定，改完再一次切版。代價是「改了沒生效」成為最常見的假故障。

判讀的訣竅是問一個問題：這次觸發是自己按的，還是外面打進來的。自己按的走編輯器最新碼，外面打進來的走部署版本。症狀是「手動測試都對、實際收到的資料卻是舊格式」時，答案幾乎必定是部署版本沒更新。

更新的操作是「管理部署作業 → 編輯 → 版本選新版本 → 部署」，這會保持網址不變（web app 部署的更新語意）。用「新增部署作業」會產生新網址，前端設定的端點就對不上了——這一點與模組一的部署模型講的是同一件事，只是從故障診斷的方向再看一次。

驗證用執行項目頁面：它列出每一次 doPost 的執行時間、耗時與狀態。這個頁面能回答一個關鍵問題——請求到底有沒有打到端點：

• 有執行紀錄但狀態失敗：請求送達了，接收端出錯
• 完全沒有對應時間的執行紀錄：請求根本沒送達，問題在瀏覽器端或網路

這個分岔把排查範圍砍半，而且它的證據來自平台本身，不依賴任何推測。實際運用的例子是判斷「某些記錄只有離開事件、沒有進入事件」的成因：執行紀錄裡完全找不到進入事件對應時間的執行，因此問題落在接收端之前——請求根本沒送出來。

這一步能確定的就到這裡。再往下的「為什麼沒送出來」屬於假說，執行紀錄支撐不了它：可能是那個瀏覽器環境攔截了頁面載入期間的請求，也可能是接收端當時併發撞頂而請求被拒（那會留下失敗紀錄，可以排除），或是網路瞬斷。把觀測與解釋分開記錄，之後拿到更多樣本時才知道哪一個假說被推翻了。

靜默失效：合法執行、輸出合法、數字是錯的

第三類故障持續執行、持續產出看起來合理的數字，而數字是錯的——前兩類至少會停下來。

試算表的分類公式是典型場所，而它最難察覺的形態是「修正一個問題時引入下一個」。事件模型那一章示範過第一次：單事件模型下的計數條件在雙事件模型下永遠不成立，那個分類的計數從此恆為零。

修法是把事件型別加進條件，而修正版的開頭多了一句「非進入事件的列一律留白」——避免同一次瀏覽被計數兩次。第二次失效就出在那一句。 它預設每次瀏覽都有進入事件，而真實資料裡存在只有離開事件的記錄（成因見上一節）。這些列被開頭那個條件整批留白，於是一整類資料在統計裡完全不存在——這不是算錯，是那一類從報表上消失了。

兩次的共同形態相同：公式沒有語法錯誤、沒有回傳錯誤值，只有分佈變了。

零是這裡最危險的輸出，因為它與「沒有這種流量」完全不可區分。 要察覺算錯，得先有一個獨立來源知道這裡本來應該有多少——而分析公式存在的理由，正是因為沒有那個獨立來源。

三個作法讓這類失效可被發現：

用總量守恆檢查涵蓋。 分類後各類數量的總和與原始列數的差額應該為零。差額不為零代表有資料形狀沒被任何條件接住，而這個檢查不要求預先知道漏了什麼——這是它比逐條檢視有效的地方。

讓未涵蓋的資料顯示成標籤而非留白。 分類邏輯的最後放一個 catch-all 分支，把沒被接住的列標成「未分類」。留白與「不適用」在視覺上不可區分，而一個會被看見的標籤才有機會促使人去查。

資料模型變更時把公式的重算納入同一次變更。 分析邏輯是資料模型的下游依賴，與欄位定義、寫入程式碼屬於同一次變更的範圍——延後處理的代價與重算的方法見事件模型那一節的示範。

抽象層的完整推導見 #250 資料多出一種形狀時，既有分析邏輯靜默換語意。

診斷順序

三類故障的排查有一個共通的推進方式：沿著資料的路徑，逐段確認實際狀態，而不是逐段確認程式碼寫了什麼。

三段的觀測值需要補充。瀏覽器那一段看的是請求有沒有發出，而它沒發出通常有兩個良性成因：beacon 前端有一道網域判斷（只在正式站送、本機預覽不送），以及讀者可能設過退出標記——兩者都會讓程式在送出前就返回，看起來與故障相同。

傳輸途中那一段是「發出了但沒抵達」的落點。接收端是一個外部網域，廣告與隱私擴充功能的通用規則可能直接擋下這個請求；瀏覽器的網路面板會顯示它被封鎖而非失敗。這一段存在的理由是前後兩段都答不了它：瀏覽器說「我送了」、執行紀錄說「我沒收到」，兩邊都沒說謊。

彙總排程那一段容易被漏掉，因為它不在 beacon 的即時路徑上。定時彙總讀的是同一張表，而它有自己的一組常數（讀幾欄、事件型別在第幾欄），資料模型變更時它們與分析公式同樣需要重算。

試算表那一段看的是最新一列的時間戳與欄位對位。欄位錯位與資料沒寫進去是兩種不同的故障——前者每一格都有值、看起來完全正常，成因是寫入端的欄位順序與表頭不同步，而它不會產生任何錯誤。

每一段都有一個「不看程式碼就能得到的觀測值」，這是這張表的設計重點。讀程式碼只能知道它宣稱會做什麼，而這幾類故障的成因全都是宣稱與實際之間的落差——落差只有實際觀測才看得見。

下一步

收集鏈確認健康之後，資料判讀的環節分別是：識別欄位見訪客識別與 opt-out、行為欄位見事件模型與停留時間、判定規則見辨識自動化流量、而這些欄位加總起來涵蓋了誰見這份統計的分母是什麼。配額耗盡導致的漏記是另一類成因，見模組五的配額碰撞與防濫用。

概念位置

流量統計用它把 beacon 累積的原始 log 每天彙總成一張日報表，實作見模組四。

可觀察訊號與例子

時間觸發器可以設成每分鐘、每小時、每天固定時段、或每週執行。典型用法是「每天凌晨把前一天的 raw log 依日期與路徑 group 成彙總表」，讓人打開試算表看到的是整理過的數字、而不是逐筆原始紀錄。

判讀方式

觸發器的成本受執行配額約束：個人帳號所有觸發器每天總執行時間上限 90 分鐘。所以彙總邏輯要寫得有效率，資料量大時避免每次都全表掃描——這條線在原始 log 累積到很多列時才會逼近，判讀與最佳化見模組三：Sheets 的容量邊界。

觸發器是 Apps Script 從「被動等人呼叫」變成「主動定時執行」的機制。它的成本要放在心上：個人帳號的觸發器每天總執行時間上限是 90 分鐘（見模組零），所以彙總邏輯要寫得有效率，別在觸發器裡做會逼近上限的重活。

章節文章

跨分類引用

• → 模組三：Sheets 當資料庫：被彙總的 raw log 從哪來
• → Monitoring：漏斗分析：彙總後的資料能做什麼分析

概念位置

這個頁面回答的問題是「請求有沒有抵達端點」，而它把故障範圍切成兩半：有執行紀錄但狀態失敗代表請求送達了、接收端出錯；完全沒有對應時間的執行紀錄代表請求根本沒送出來，問題在瀏覽器端或網路。兩者的排查方向相反，而在此之前它們的症狀完全相同——試算表都沒有新資料。

它與 Logger.log 的分工也在這裡：Logger 記錄的是程式自己選擇要說的話，執行項目記錄的是平台觀察到的事實，程式在第一行就爆掉時前者什麼都沒有、後者仍有一列失敗紀錄。判讀失敗紀錄時常要對照執行配額的三條上限，因為逼近上限的症狀（耗時拉長、密集失敗）都先出現在這一頁。

可觀察訊號與例子

一次正常的 beacon 接收在這裡是「doPost / 網頁應用程式 / 一秒出頭 / 已完成」。耗時異常拉長是逼近執行配額單次上限的前兆；同一時段出現大量失敗則指向併發撞頂。

版本欄位還洩漏另一件事：它顯示這次執行用的是哪一個部署版本，因此「程式碼改了但端點跑舊版」這個假故障在這裡看得出來。

判讀方式

排查「資料沒進來」時先開這一頁，再決定往哪個方向查——這一步的成本是開一個頁面，而它省下的是往錯誤方向排查的整段時間。實際運用見假故障與靜默失效的診斷。

靜態站的能力邊界很明確：瀏覽器把 HTML/JS 抓下來後，所有邏輯都在使用者的瀏覽器裡跑，沒有任何一段程式碼在你控制的伺服器上執行。這代表任何「要記在你這邊」的資料——誰來看過、表單填了什麼、累積計數——都需要一個瀏覽器以外、由你掌握的接收端。這個接收端不必是傳統伺服器；它可以是一段掛在免費平台上、只在被呼叫時才執行的函式。本指南教怎麼用這種函式把靜態站的能力補齊。

貫穿全指南的案例是「幫這個架在 GitHub Pages 上的 blog 做流量統計」。GitHub Pages 不給 access log、也不能跑伺服器端程式碼，所以流量資料只能靠瀏覽器主動回報。這個案例會從模組零的架構推導、一路實作到模組六的資料判讀，讀者跟著做完會得到一個真的能用、資料存在自己試算表裡的流量統計系統——「自己手上」在這裡指的是資料的控制權與查詢自由，基礎設施仍然是 Google 託管的。

第一種膠水工具選 Google Apps Script + Google Sheets：它對個人 Google 帳號免費、不需要信用卡、Sheets 直接當資料庫兼儀表板，起步門檻是所有選項裡最低的。指南後續會加入其他膠水工具（例如 Cloudflare Workers）作為對照，說明各自的適用邊界——Apps Script 適合資料量小、需要人可直接讀寫試算表的場景；當量體變大或需要低延遲時，模組五會給出換工具的判準與遷移路徑。

教材邊界

流量分析的概念層（事件分類、漏斗、cohort、歸因）不在本指南，在 Monitoring 監控體系。本指南是動手做的那一半：怎麼用免費工具把資料真的收進來、存起來、彙總出報表。兩者互補——先看 Monitoring 想清楚要收什麼，再回本指南把管線搭起來。

Backlog

跨模組那一列是目前唯一的結構性不對稱：本指南對 monitoring 有五條引用，反向零條，而 monitoring 的漏斗與 cohort 分析都預設資料乾淨、可識別、無機器混入——那些前提正是模組六在處理的。

模組六補上了資料判讀，但彙總層仍停在模組四的單事件版本——那裡目前只標明了前提與修法方向，尚未有一篇把「配對進入與離開事件、算出平均停留與閱讀深度」實作出來。順序上它依賴模組六的事件模型定案，因此排在其後。

章節

模組零到五走的是「怎麼把管線接起來」，那條路徑上的每個障礙都能從文件讀出來。模組六的位置不同——它處理管線接好、資料真的開始累積之後才浮現的問題：來源網址大量空白、任兩列之間看不出是不是同一個人、真人與機器抓取混在一起。這些無法在設計階段推導，只有真實流量打進來才會現形。

讀者旅程

想直接把流量統計做出來：模組零建立架構直覺後，跳模組二照著實作，缺概念再回模組一補。想完整理解這套膠水模式、之後套用到其他專案：模組零到六順讀。已經收到資料、正要開始看報表：直接進模組六。只想查某個 Apps Script 術語：看 knowledge-cards。

這個 blog 架在 GitHub Pages 上，是純靜態託管——瀏覽器把頁面抓下來後所有邏輯都在使用者端跑，GitHub 的伺服器不給 access log、也不能執行我的程式碼。這代表「有人來看過哪一頁」這個事實，預設沒有留在任何我查得到的地方。想知道流量、又不想為此租一台主機，唯一的切入點是頁面裡的 JavaScript：讓它在載入時主動送一則瀏覽事件到一個我掌握的接收端。這種請求叫 beacon，接收端這裡用 Google Apps Script、資料存進 Google Sheet。

這篇記錄的是「這個 blog 實際怎麼接線」，延續先前 Hugo + Bear Cub 主題設定的 blog 紀錄脈絡。beacon → Apps Script → Sheet 這套架構背後的通用方法論、選型理由、Google 端的完整部署步驟，整理在免伺服器自動化實務指南；這裡只講落在本 blog Hugo 版型上的那一段，以及實作時撞到、官方文件不會告訴你的一個編碼落差。

版型注入點：baseof 已備好的 custom_body

Bear Cub 主題的 baseof.html 在關閉 </body> 前留了一個擴充點：

1{{- partial "custom_body.html" . -}}

這正是 beacon 該進的地方——放在 body 結尾、頁面主要內容都載入後才送，不跟關鍵資源搶頻寬。做法是在 layouts/partials/ 建一個 custom_body.html，主題會自動引入。這樣 beacon 邏輯集中在一個 partial 裡，不必動主題檔、不必改每一個版型。

beacon partial 與開關參數

beacon 的網址不寫死在版型裡，而是讀 hugo.toml 的一個站台參數。這樣做有兩個好處：網址換部署時只改 config、不動程式；參數留空時 partial 完全不輸出，等於一個乾淨的開關。

layouts/partials/custom_body.html：

 1{{- with .Site.Params.analyticsBeacon }}
 2{{- $host := (urls.Parse $.Site.BaseURL).Host }}
 3<script>
 4  (function () {
 5    // 只在正式站送，本機 hugo server 預覽（localhost）不計入統計
 6    if (location.hostname !== {{ $host }}) return;
 7    // 粗粒度分類閱讀裝置，只送 mobile / tablet / desktop，不送完整 userAgent
 8    function deviceType() {
 9      var ua = navigator.userAgent;
10      var iPadAsMac = /Macintosh/.test(ua) && navigator.maxTouchPoints > 1;
11      if (/iPad|Tablet|PlayBook|Silk/.test(ua) || iPadAsMac || (/Android/.test(ua) && !/Mobile/.test(ua))) return "tablet";
12      if (/Mobi|iPhone|iPod|Android|BlackBerry|IEMobile|Opera Mini/.test(ua)) return "mobile";
13      return "desktop";
14    }
15    var payload = JSON.stringify({
16      path: location.pathname,
17      ref: document.referrer || "",
18      lang: navigator.language || "",
19      dev: deviceType()
20    });
21    var blob = new Blob([payload], { type: "text/plain;charset=UTF-8" });
22    navigator.sendBeacon({{ . }}, blob);
23  })();
24</script>
25{{- end }}

hugo.toml 的 [params] 加一行，部署好 Apps Script 後把 /exec 網址填進來就啟用，留空字串就停用：

1[params]
2  # 免伺服器流量統計 beacon：部署 Apps Script web app 後，把 /exec 網址填進來即啟用。
3  # 留空字串代表停用（partial 不會輸出任何 script）。
4  analyticsBeacon = ''

三個設計決定值得說明。用 .Site.Params.analyticsBeacon 當開關，讓「啟用統計」變成一個 config 動作而非改程式，也讓公開的版型檔裡不出現部署網址。hostname guard 從 .Site.BaseURL 推導（urls.Parse 取 host），而不是寫死字串，換 domain 時不用改 partial；它的作用是讓本機 hugo server 預覽時的瀏覽不混進統計——localhost 不等於正式 host，beacon 就不送。送 text/plain 而非 application/json，是為了讓這個跨網域請求成為 CORS simple request、不觸發 preflight；Apps Script 的 web app 無法回應 preflight 的 OPTIONS，用 JSON 送會被擋，這條雷的細節在前端 beacon 與 CORS 障礙。

payload 除了路徑、來源、語言，還送一個粗粒度的閱讀裝置標籤 dev（mobile / tablet / desktop），讓我知道讀者用什麼裝置看——這對排版決策有用（例如某篇長表格文章若行動裝置佔比高，就值得檢查手機上的可讀性）。分類刻意只送三選一的標籤、不送完整 userAgent，維持不記 PII 的一致立場。實作上有個要補的判斷：iPadOS 的 Safari 會把 userAgent 偽裝成 Mac 桌機，單看字串會把 iPad 誤判成 desktop，得靠 navigator.maxTouchPoints > 1 搭配 Macintosh 字樣補抓成 tablet。

實跑撞到的雷：script context 的雙重編碼

第一版的 partial 我在插值上多加了 jsonify，想說手動把值轉成 JSON 字串比較保險：

1if (location.hostname !== {{ $host | jsonify }}) return;
2navigator.sendBeacon({{ . | jsonify }}, blob);

build 出來的結果是壞的：

1if (location.hostname !== "\"tarrragon.github.io\"") return;
2navigator.sendBeacon("\"https://script.google.com/macros/s/.../exec\"", blob);

網址被包成 "\"...\""——兩層引號。JS 會把「含引號的整串」當成字串值，sendBeacon 打的是一個帶引號的壞網址，beacon 靜默失敗。

根因是 Hugo 底層的 Go html/template 是 context-aware 的：當插值出現在 <script> 區塊裡，它會自動把值當 JS 來輸出，字串會被轉成安全的、帶引號且已跳脫的 JS 字串字面量。也就是說 {{ $host }} 在 script context 裡本來就會渲染成 "tarrragon.github.io"。我再套一層 jsonify，等於編碼兩次。正解是移除 jsonify，直接寫 {{ $host }} 和 {{ . }}，讓 template 的 context-aware escaping 自己處理——這同時比手動加引號更安全，因為它會針對 script context 正確跳脫。

這種落差官方文件的 fact-check 抓不到：jsonify 和 sendBeacon 各自的文件都正確，錯在「兩者疊在 script context」這個組合。只有真的 build 出來、看渲染結果才會發現。

啟用與驗證

blog 端接好後，啟用一次走三步：

1. 依免伺服器自動化實務指南部署 Apps Script web app，拿到 /exec 網址。
2. 把網址填進 hugo.toml 的 analyticsBeacon，push 讓 GitHub Pages 重建。
3. 打開線上任一頁，回 Google Sheet 看第二列是否出現一筆瀏覽紀錄。

要在本機先確認 partial 有正確渲染、又不真的送出，可以用環境變數覆蓋參數 build，再 grep 產物：

1HUGO_PARAMS_ANALYTICSBEACON="https://script.google.com/macros/s/TESTID/exec" \
2  hugo --destination /tmp/hb
3grep -n "sendBeacon" /tmp/hb/automation/index.html

看到 navigator.sendBeacon("https://.../exec", blob) 這種乾淨的字串字面量、而不是帶跳脫引號的版本，就代表注入正確。hostname guard 也會一起出現在同一段，確認 location.hostname !== "tarrragon.github.io" 這條有生效。

部署前用 curl 直接驗接收端

blog 的 beacon 只在正式站送，所以「等 push 上線再看 Sheet」的驗證回饋很慢。更快的做法是用 curl 模擬一則 beacon、直接打 /exec，把 Google 端（部署、doPost、寫入）跟 blog 端拆開驗——Google 端通了再談上線：

1URL='https://script.google.com/macros/s/你的部署ID/exec'
2curl -sS -L -H "Content-Type: text/plain;charset=UTF-8" \
3  --data '{"path":"/test","ref":"","lang":"zh-TW","dev":"desktop"}' "$URL"
4# 預期輸出：{"ok":true}，並在 Sheet 多出一筆 /test 列

這段 curl 有兩個容易踩錯、值得記住的點。用 --data 觸發 POST，不要加 -X POST。 GAS web app 的 POST 成功後會回一個 302、把 doPost 的輸出放在跳轉後的 googleusercontent.com echo 端點；curl 遇到 302 預設會轉成 GET 去取那個輸出，這是對的。一旦加了 -X POST，curl 會強迫連跳轉後都用 POST，打壞 echo 端點、回一個 Google 雲端硬碟的「很抱歉，目前無法開啟這個檔案」錯誤頁——看起來像部署壞了，其實只是測試指令的方法用錯。瀏覽器的 sendBeacon 沒這問題，這是 curl 特有的落差。

302 是成功、不是錯誤。 GAS web app 的 POST 正常就是回 302，doPost 在請求打到 /exec 的當下已經執行、資料已經寫進 Sheet，跳轉只是去取回應。所以就算 curl 那端因為方法用錯而讀不到 {"ok":true}，那一筆其實也已經寫進去了——診斷時先去 Sheet 看有沒有新列，比盯著 curl 的輸出準。

如果連 GET 打 /exec 都回「無法開啟檔案」（而不是 GAS 的 找不到指令碼函式：doGet），那才是部署層的問題，優先查「誰可以存取」是不是「所有人」。

這個 /exec 網址該公開嗎

這個網址必然是公開的，而且非公開不可——它會被寫進每一頁的 client-side JS，任何人檢視原始碼都看得到。這是 client beacon 架構的本質，不是設定失誤；GA、Cloudflare 那些的收集端點也全是公開的。所以安全的問題不是「怎麼把它藏起來」，而是「限制別人拿它能做什麼」。

別人拿到這網址讀不到你的 Sheet：doPost 只做 appendRow 然後回 {"ok":true}，不回傳任何試算表內容，授權範圍也只綁這一張表。真正的風險是騷擾型的兩種——有人直接 POST 垃圾內容污染統計、或狂打端點吃掉執行配額。對沒沒無聞的個人 blog，攻擊者缺乏動機，這兩者機率都很低。要進一步限制破壞範圍（例如 payload 放一個約定 token、doPost 對不上就丟掉），屬於配額與濫用防護的層次——注意 token 也在 client JS 裡看得到，它擋隨手亂打、擋不了鐵了心的人。

完整方法論

這篇只涵蓋 Hugo 版型這一段。beacon 該送什麼、Apps Script 接收端怎麼寫、Sheets 當資料庫的並發與容量、觸發器怎麼把原始 log 彙總成日報、以及匿名端點的配額與濫用防護，都在免伺服器自動化實務指南。想把同一套搬到別的靜態站或別的膠水工具（例如 Cloudflare Workers），也從那裡的模組零選型開始。