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 變成看得懂的日報，見模組四：觸發器與排程。