appendRow：單筆寫入

appendRow 在表格最後一列的後面新增一列，是 log 型資料最自然的寫法——每個事件就是一列、append 到尾巴。它一次接一個陣列、對應各欄：

1sheet.appendRow([new Date(), data.path, data.dev]);

appendRow 的好處是它自己找「最後一列的下一列」，不必你算行號。對「一次寫一筆瀏覽」這種場景，它是最直接的選擇。要注意它是「整列 append」——如果需要一次寫很多列（例如批次彙總），逐筆呼叫 appendRow 會慢，那時改用 getRange(...).setValues(二維陣列) 一次寫一整塊，效能差很多。單筆用 appendRow、批次用 setValues，是 Sheets 寫入的基本分工。

並發：兩個 doPost 同時 append 會怎樣

Apps Script 允許多個執行實例同時跑（個人帳號上限 30 個併發）。當兩個 beacon 幾乎同時到達，平台會起兩個 doPost 實例並行執行，兩者都呼叫 appendRow。多數情況下 Google 會把兩次 append 排到不同列、相安無事；但在高並發下，「兩個實例同時判斷『最後一列是第 100 列』、都想寫第 101 列」的競態是可能發生的，結果是一筆覆蓋另一筆、少記一筆。

這個風險要不要處理，取決於你的瞬間併發有多高。個人 blog 的流量分散在整天，任何一刻同時到達的 beacon 通常是個位數甚至零，競態機率極低、就算偶爾少記一筆對「哪篇有人看」的判斷也無影響——這種情境不必加保護，保持 appendRow 的簡單。真正需要處理的是「短時間尖峰」：某篇文章被大量分享、一分鐘湧入幾百次瀏覽，這時並發拉高、競態才變得值得防。

LockService：需要時才序列化

要防競態，用 LockService 把寫入序列化——讓同一時間只有一個執行實例能進入寫入區段，其他的排隊等它做完：

 1function doPost(e) {
 2  var lock = LockService.getScriptLock();
 3  lock.waitLock(5000); // 最多等 5 秒拿鎖
 4  try {
 5    var data = JSON.parse(e.postData.contents);
 6    SpreadsheetApp.getActiveSpreadsheet().getSheetByName("工作表1")
 7      .appendRow([new Date(), data.path || "", data.dev || ""]);
 8  } finally {
 9    lock.releaseLock(); // 一定要放，否則後面全部卡住
10  }
11  return ContentService.createTextOutput(JSON.stringify({ ok: true }))
12    .setMimeType(ContentService.MimeType.JSON);
13}

getScriptLock 取的是整個腳本共用的鎖，保證所有 doPost 實例排隊寫入。waitLock(5000) 是「最多等 5 秒」——等不到就丟例外（併發高到 5 秒還排不進來，這筆放棄，總比無限等好）。releaseLock 必須放在 finally，確保就算中間出錯也會釋放，否則鎖沒放、後面的請求全部卡死。

加鎖的代價是寫入從並行變序列，尖峰時每筆要多等前面的做完，吞吐下降。所以它是「有並發競態風險時才加」的保護，不是預設就要有的東西。判斷訊號回到前面那句：瞬間併發會不會高到讓競態實際發生——不會就別加，會就加上。這也是為什麼流量統計的基本版 doPost（模組二）刻意不含 lock：先讓簡單版跑起來，等真的遇到尖峰漏記，再加這一層。

下一步

寫入處理好了，資料表本身怎麼設計、以及 Sheets 累積到多大會撐不住，見資料模型與容量邊界。

raw log 的欄位設計

raw log 表每一欄對應一個固定的維度，每一列是一筆完整的事件。流量統計的 raw log 大致是：

三個設計決定讓這張表好用又好彙總。時間放第一欄、用接收端的伺服器時間，讓資料天然按寫入順序排列，也讓「某天的資料」用時間範圍就能篩。每一欄都是原子維度、不把多個資訊塞進一欄（不要把「路徑+裝置」合併成一欄），因為彙總時要能單獨 group by 路徑、或單獨 group by 裝置，欄位分開才做得到。只 append、不回頭改已寫的列，讓這張表成為不可變的事實紀錄——要改的是彙總結果、不是原始 log，原始資料保持乾淨才能隨時重算。

raw log 直接看沒有意義（幾千列逐筆瀏覽），它的價值是當彙總的原料。把 raw log 依日期與路徑 group 成「每天每篇看幾次」的日報，是模組四：觸發器與排程的工作。

Sheets 的容量邊界

Sheets 是為「人看的試算表」設計的，不是高吞吐資料庫，所以它有兩類上限要放在心上。

總 cell 數上限：單一試算表有一個總儲存格數量的硬上限（目前以千萬 cell 計，Google 會不定期調整，實際數字以官方為準）。raw log 每列的 cell 數等於欄數，5 欄的話，這個上限換算成列數是相當大的量——對個人 blog 是好幾年的資料，不會很快碰到。但它是有限的，不是無限成長。

讀寫效能隨列數下降：實務上先浮現的邊界是效能，比硬上限更早遇到。當 raw log 累積到數萬、數十萬列，任何「整表讀進來算」的操作（例如彙總 trigger 每次全表掃描）會越來越慢，可能逼近觸發器的單次 6 分鐘執行上限。

撐不住的訊號與應對

判斷 Sheets 開始撐不住，看這幾個訊號：彙總 trigger 的執行時間逐月變長、逼近 6 分鐘；開啟試算表本身變慢、捲動卡頓；或 cell 數逼近上限的警告。出現這些訊號時，有兩條應對路徑，依情況選：

分表：把 raw log 按月（或按季）拆成多張工作表，例如 log-2026-07、log-2026-08。彙總 trigger 只讀當月表、不必掃全部歷史，執行時間就回到穩定。這是最小改動、繼續留在 Sheets 的做法，適合量成長但還在 Sheets 能力範圍內。

遷移：當量大到連分表都吃力、或需要更即時的查詢，訊號就指向「該換更重的儲存」——把接收端從 Apps Script 換成 Cloudflare Workers + D1（免費 SQLite），資料庫的查詢能力與吞吐遠高於 Sheets。遷移的完整訊號與路徑在模組五，選型的取捨在模組零。

判準用一句話收斂：Sheets 撐不住的第一訊號通常是彙總變慢、不是 cell 爆掉——先分表爭取空間，分表也吃力才談遷移。對絕大多數個人 blog，這些邊界很久才會碰到，先讓簡單版跑著、留意訊號即可。

事件模型會改變這裡的估算

上面的估算假設一次瀏覽產生一列。模組六的事件模型把它改成一進一離兩列，並在 payload 上多加六個欄位——列數接近翻倍、單列的 cell 數從五增為十一，兩者相乘之後容量上限會比這裡算出來的早很多抵達。真要估的話，用那一章的欄位清單重算一次，而不是沿用這一節的數字。

下一步

資料進來、也知道表能長多大之後，把 raw log 變成看得懂的日報，見模組四：觸發器與排程。

Sheets 適合的場景是資料量小到中等、需要人直接讀寫的流量統計。它撐不住的訊號很明確：列數到數萬列後讀寫變慢、瞬間併發逼近 30 時出現寫入衝突。碰到這些訊號時的判斷與遷移路徑，見模組五。

章節文章

跨分類引用

• → 模組二：接收端 handler：資料怎麼進到 Sheet 的
• → 模組四：觸發器與排程：把 raw log 彙總成報表
• → 模組五：部署、配額與安全：Sheets 撐不住時怎麼判斷與遷移

靜態站的能力邊界很明確：瀏覽器把 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。