本文是 Firestore overview 的 deep article。寫作參照 Vendor 深度技術文章寫作方法論。寫入限制以 官方 best practices 為準、最後檢查日 2026-06-16。

問題情境：一個讚數欄位拖垮整條寫入

直播平台上線一個「即時按讚數」功能：每個貼文一個 document，按讚就 update 它的 likes 欄位 +1。內測沒問題，上了熱門直播——同一個貼文每秒湧入上千次按讚，寫入開始大量失敗、retry，延遲飆高，連帶其他寫入路徑被拖累。

根因是流量全壓在單一 document 上，而非流量總量超過 Firestore。Firestore 對單一 document 的持續寫入有軟上限（官方長期建議維持在每秒個位數量級、以當前文件為準），因為每次寫入要更新該 document 的所有索引、且並行寫同一 document 會觸發 contention 重試。把高頻變動的值塞進一個 document，等於替自己造一個寫入熱點。這篇處理 contention 的成因、用 distributed counter 把熱點打散的實作，以及這個手段的能力邊界。

核心概念：寫入 contention 從哪來

Firestore 的寫入成本不只是「寫一個值」。理解 contention 要抓三點：

每次寫入維護該 document 的所有索引。document 上有幾個被索引的欄位，一次寫入就要更新幾份索引條目。索引越多、單次寫入越重，這是寫入吞吐與索引數量綁定的根因。

並行寫同一 document 會序列化。Firestore 保證單一 document 的寫入一致性，並行的 +1 不能各寫各的——它們競爭同一份狀態，後到的要重試。transaction 與 FieldValue.increment() 都受這個限制：increment 省掉「讀-改-寫」的來回，但多個 increment 打同一 document 仍在同一個寫入熱點上排隊。

熱點是 per-document，不是 per-collection。把 1000 個貼文的讚數分在 1000 個 document，每個 document 每秒個位數寫入，完全沒問題；問題只在「單一 document 每秒上千寫入」。所以解法的方向是把一個邏輯計數拆成多個物理 document。

配置：distributed counter 分片計數

distributed counter 的核心是把「一個計數」拆成 N 個 shard document，寫入時隨機挑一個 shard +1，讀取時把所有 shard 加總。寫入壓力被分散到 N 個 document，每個 shard 的寫入頻率降為原本的 1/N。

資料結構：在計數目標下建一個 shards subcollection，N 個 shard document，每個存一段 partial count。

 1// counter.js（用 Firebase Web SDK v9 modular API）
 2import {
 3  doc, collection, runTransaction, getDocs,
 4  writeBatch, increment,
 5} from 'firebase/firestore';
 6
 7const NUM_SHARDS = 10;
 8
 9// 初始化：建立 N 個 shard、每個 count = 0
10export async function createCounter(db, counterRef) {
11  const batch = writeBatch(db);
12  for (let i = 0; i < NUM_SHARDS; i++) {
13    batch.set(doc(counterRef, 'shards', String(i)), { count: 0 });
14  }
15  await batch.commit();
16}
17
18// 寫入：隨機挑一個 shard +1（用 increment 省掉 read-modify-write）
19export async function incrementCounter(db, counterRef) {
20  const shardId = Math.floor(Math.random() * NUM_SHARDS);
21  const shardRef = doc(counterRef, 'shards', String(shardId));
22  await setDoc(shardRef, { count: increment(1) }, { merge: true });
23}
24
25// 讀取：加總所有 shard
26export async function getCount(db, counterRef) {
27  const snap = await getDocs(collection(counterRef, 'shards'));
28  let total = 0;
29  snap.forEach((s) => { total += s.data().count; });
30  return total;
31}

三個設計點要展開。第一，寫入用 increment(1) 而非 transaction 的讀-改-寫：increment 是 atomic 的 server-side 操作，省掉一次讀取，且本身就避開了「讀到舊值再寫」的 race。第二，shard 選擇用隨機分佈，讓寫入均勻打散到 N 個 shard——這是分片有效的前提，若選 shard 有偏（例如按 user id hash 但 user 分佈不均），熱點會在某幾個 shard 復現。第三，讀取要讀 N 個 document 加總，這是分片的代價：寫入便宜了，讀取從「讀 1 筆」變成「讀 N 筆」，計費與延遲都乘以 N。

如果即時讀取頻率也很高（每個觀眾畫面都要顯示即時讚數），讀 N 個 shard 的成本會反過來變成瓶頸。這時把彙總值定期寫回一個 summary document，client 訂閱 summary 而非每次加總：

1// 由 Cloud Function 定時（或 onWrite 觸發 + debounce）彙總寫回 summary
2export async function aggregateToSummary(db, counterRef) {
3  const total = await getCount(db, counterRef);
4  await setDoc(doc(counterRef, 'summary', 'current'), {
5    count: total,
6    updatedAt: serverTimestamp(),
7  });
8}

這把「即時精確」換成「近即時」：summary 有刷新間隔的延遲，但讀取從 N 筆降回 1 筆。讚數、觀看數這類「差幾個不影響體驗」的計數，這個取捨幾乎總是對的。

故障演練：五個高頻寫入踩坑

Case 1：直接 increment 單一 document 沒分片

最常見的起手——以為 FieldValue.increment() 就解決了並行，忽略它仍在單一 document 的寫入熱點上。低流量沒事、熱門事件寫爆。修法：判斷該計數的峰值寫入頻率，超過單 document 軟上限就上 distributed counter；不確定峰值就先分片，分片對低流量無害（只是多讀幾筆）。

Case 2：shard 數量拍腦袋定太小

設了 3 個 shard，峰值流量下每個 shard 仍每秒上百寫入、照樣 contention。修法：shard 數要對齊峰值寫入頻率除以單 shard 安全寫入率（每秒個位數）。預期峰值每秒 500 寫入、單 shard 安全 5/s，就需要約 100 個 shard。寧可估高。

Case 3：shard 太多拖垮讀取

反向錯誤——為了保險設 1000 個 shard，結果每次讀計數要讀 1000 個 document，讀取計費與延遲爆炸。修法：shard 數是寫入分散與讀取成本的取捨；高寫入低讀取用多 shard + 直接加總，高寫入高讀取用多 shard + summary 彙總，別用「讀 N 筆加總」硬扛高頻讀取。

Case 4：選 shard 有偏導致熱點復現

用 userId 的 hash 選 shard、但活躍 user 集中在少數，寫入仍打在某幾個 shard 上。修法：shard 選擇要與寫入來源無關的隨機分佈，不要綁任何可能傾斜的 key。

Case 5：把分片計數當強一致餘額用

把 distributed counter 拿來記帳戶餘額、庫存這類需要強一致與精確讀的值。分片計數的讀取是「加總當下各 shard」，並行寫入下讀到的是近似值，不適合做扣款判斷。修法：強一致的計數（餘額、庫存、配額）不該用分片計數，也通常不該用 Firestore 的單欄位累加——這類值要走 transaction 嚴格控制、或放關聯式資料庫用 row lock，見邊界段。

容量與觀測：shard 數的估算與監控

shard 數量的估算從峰值寫入頻率反推：shard 數 ≈ 峰值每秒寫入 / 單 shard 安全寫入率。單 shard 安全寫入率以官方當前的單 document 持續寫入建議為基準（個位數量級），估算時取保守值。讀取成本同步要算：每次讀計數 = N 次 document read，乘上讀取頻率與日活，這是 distributed counter 的隱性帳。

監控的訊號是寫入失敗率與 contention 重試。寫入大量失敗 + retry 是 contention 的直接徵兆；單一 shard 的寫入頻率若明顯高於其他 shard，是 shard 選擇有偏的徵兆。這些訊號接回 4.20 Observability Evidence Package，把高頻寫入的健康度當成可觀測指標而非事故才發現。

容量規劃還要考慮 shard 數的可調整性：shard 數寫死在 client 程式裡，事後要加 shard 得同時改寫入與讀取邏輯、並補建新 shard document。預期會成長的計數，起步就把 shard 數設在峰值對應的量級，比事後擴容省事。

邊界與整合：什麼計數不該用分片，什麼該離開 Firestore

distributed counter 解的是「高頻、可接受近似、不需強一致」的計數——讚數、觀看數、瀏覽量、即時參與人數。它的邊界很清楚：

• 需要強一致與精確的計數：帳戶餘額、庫存、配額扣減。這些要嘛用 Firestore transaction 嚴格序列化（但就回到單 document 寫入上限的限制、不適合高頻），要嘛放關聯式資料庫用 row-level lock 與交易保護（見 1.3 transaction 與一致性邊界）
• 需要任意維度聚合的計數：要算「各地區、各時段的累計」這類多維彙總，分片計數表達不了，該把事件流寫進分析系統或關聯式資料庫做 aggregation
• 計數本身是核心交易資料：當計數驅動扣款、結算這類有金錢後果的流程，把它留在 client 直連的 Firestore 是控制面風險，該移到後端——這呼應 Firestore → 自建 relational 的成本與授權 driver

判讀順序是先問「這個計數能不能容忍近似與最終一致」。能，distributed counter 是 Firestore 內的正解；不能，這個計數從一開始就不該用 Firestore 的單欄位累加表達。

下一步路由

• 上層：Firestore overview（容量特性與寫入熱點）
• 一致性邊界：1.3 transaction 與一致性邊界（強一致計數的去處）
• 容量背景：1.10 KV / Document DB 容量規劃
• 觀測：4.20 Observability Evidence Package（寫入失敗率與 contention 監控）
• 官方：Firestore best practices、Distributed counters solution

本文是 Firestore Hands-on 操作路線 的 lab，實作 distributed counter 高頻寫入 deep article 的機制。前置環境見 Local emulator quickstart。

Firestore distributed counter lab 的核心責任是把「分片計數」從概念變成可觀察的寫入分佈與彙總結果。這個 lab 在 emulator 上建立 N 個 shard、隨機分片寫入大量 increment、檢查寫入是否均勻打散到各 shard、再讀取彙總驗證總和正確。

本文的驗收標準是：你能跑出一個 sharded counter、看到 N 個 shard 各自累積了大致均勻的 partial count、彙總後等於總寫入次數，並理解 emulator 能驗什麼、不能驗什麼。

先講清楚 emulator 的邊界

這個 lab 驗證的是分片計數的機制正確性：寫入是否均勻分佈、彙總是否等於總和、讀取要讀幾個 document。它不驗證的是 contention 本身——emulator 不強制 production 的單 document 持續寫入軟上限，所以「不分片會寫爆」這件事在 emulator 跑不出來。contention 是 production 的規模特性，要在雲端真實負載下才會出現。

這個分界本身是要學的判讀：emulator 證明「分片計數做對了」，雲端負載測試才證明「不分片會撞牆」。把兩者混為一談會誤以為 emulator 全綠就代表 production 安全。

Lab 環境

沿用 quickstart 的工作區與 emulator。確認 emulator 在跑（另一個 terminal）。

1cd /tmp/firestore-lab
2# 確認 emulator 已啟動：firebase emulators:start --only firestore --project demo-firestore-lab
3export FIRESTORE_EMULATOR_HOST=localhost:8080

實作 sharded counter

counter 的核心責任是把一個邏輯計數拆成 N 個 shard document。寫入時隨機挑 shard increment(1)，讀取時加總所有 shard。這份 script 用 admin SDK 直接對 emulator 操作。

 1cat > counter.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5const FieldValue = admin.firestore.FieldValue;
 6
 7const NUM_SHARDS = 10;
 8const counterRef = db.collection('counters').doc('likes');
 9
10async function createCounter() {
11  const batch = db.batch();
12  for (let i = 0; i < NUM_SHARDS; i++) {
13    batch.set(counterRef.collection('shards').doc(String(i)), { count: 0 });
14  }
15  await batch.commit();
16}
17
18async function incrementOnce() {
19  const shardId = Math.floor(Math.random() * NUM_SHARDS);
20  await counterRef.collection('shards').doc(String(shardId))
21    .set({ count: FieldValue.increment(1) }, { merge: true });
22}
23
24async function getCount() {
25  const snap = await counterRef.collection('shards').get();
26  let total = 0;
27  const perShard = {};
28  snap.forEach((s) => { perShard[s.id] = s.data().count; total += s.data().count; });
29  return { total, perShard };
30}
31
32module.exports = { createCounter, incrementOnce, getCount, NUM_SHARDS };
33JS

三個設計點對應 deep article：用 FieldValue.increment(1) 而非讀-改-寫（避開 race）；隨機選 shard 讓寫入均勻打散；讀取要讀 N 個 shard 加總（這是分片的代價）。

跑寫入並觀察分佈

driver 的核心責任是製造大量 increment、然後檢查寫入是否均勻落在各 shard。均勻分佈是分片有效的前提——若 shard 選擇有偏，熱點會在某幾個 shard 復現。

 1cat > run.js <<'JS'
 2const { createCounter, incrementOnce, getCount, NUM_SHARDS } = require('./counter');
 3
 4const TOTAL_WRITES = 1000;
 5
 6async function main() {
 7  await createCounter();
 8  console.log(`created ${NUM_SHARDS} shards`);
 9
10  // 製造 1000 次 increment
11  const tasks = [];
12  for (let i = 0; i < TOTAL_WRITES; i++) tasks.push(incrementOnce());
13  await Promise.all(tasks);
14
15  const { total, perShard } = await getCount();
16  console.log('per-shard counts:', perShard);
17  console.log(`total = ${total} (expected ${TOTAL_WRITES})`);
18
19  // 均勻度檢查：每個 shard 期望 ~100，看極差
20  const counts = Object.values(perShard);
21  const min = Math.min(...counts), max = Math.max(...counts);
22  console.log(`min=${min} max=${max} spread=${max - min} (expected mean ~${TOTAL_WRITES / NUM_SHARDS})`);
23}
24main().then(() => process.exit(0));
25JS
26
27export FIRESTORE_EMULATOR_HOST=localhost:8080
28node run.js

預期輸出類似（實際數字每次隨機分佈而異）：

1created 10 shards
2per-shard counts: { '0': 98, '1': 105, '2': 92, ... }
3total = 1000 (expected 1000)
4min=88 max=112 spread=24 (expected mean ~100)

兩個驗收點：total 等於總寫入次數（彙總正確、沒有 increment 遺失），以及各 shard 的 count 大致落在均值附近（隨機分佈均勻、沒有單一 shard 吸走大部分寫入）。

對照實驗：讀取成本隨 shard 數成長

讀取的核心代價是讀 N 個 document。把 NUM_SHARDS 改大（例如 100）重跑，getCount 要讀的 document 從 10 變 100——這就是 deep article 講的「寫入便宜了、讀取乘以 N」的取捨。在 production 這直接反映成 read 計費。

1# 編輯 counter.js 把 NUM_SHARDS 改為 100、重跑 run.js
2# 觀察 per-shard counts 物件變成 100 個 key、getCount 讀取量 10x

這個對照讓「shard 數是寫入分散與讀取成本的取捨」從文字變成可觀察：多 shard 寫入更分散（每 shard 更少），但讀取要加總更多筆。高寫入高讀取的場景該配 summary 彙總（deep article 的進階手段），而非無限加 shard。

Artifact 與驗收

回到 production 判讀

emulator lab 證明了機制正確，但三個 production 判讀要回雲端確認：單 document 寫入軟上限（決定 shard 數要多少）、read 計費（決定 shard 數別太多 / 要不要 summary）、shard 選擇在真實流量下是否仍均勻。把 emulator 的機制驗證當第一道關，production 的容量與成本判讀見 deep article 的容量段。

Cleanup

1# 停 emulator（Ctrl-C）或清整個工作區
2rm -rf /tmp/firestore-lab

引用路徑

• 上游：Firestore Hands-on 操作路線
• Deep article：高頻寫入與 distributed counter
• 一致性邊界：1.3 transaction 與一致性邊界
• 官方：Distributed counters、Firestore best practices