官方文件路由：Firestore documentation、Firestore data model、Firestore pricing；本頁時間敏感的計費與限制 claim 以官方為準、最後檢查日 2026-06-16。

教學路線：client 直連的 document 正式狀態

Firestore 服務頁的教學目標是把「前端直接讀寫資料庫」這個存取模型的責任說清楚。讀者讀完後要能判斷 Firestore 何時是合適的正式狀態，何時因為查詢形狀、成本曲線或授權複雜度該轉向自建後端配 PostgreSQL 或留在 document model 換 MongoDB。

定位：serverless document store + BaaS 資料層

Firestore 跟 MongoDB、DynamoDB 同屬 NoSQL document / KV 家族，但承擔的責任層級不同：

• 資料組織成 collection 下的 document，document 可巢狀 subcollection，單 document 上限 1 MiB
• 沒有 server 端 JOIN，跨 collection 的關聯要靠 application 多次查詢自己組、或在寫入時反正規化
• 存取模型以 client SDK 直連為主，授權寫在 Security Rules（一套規則 DSL），而不是後端 API 的權限中介層
• 兩種營運模式：Firestore Native mode（行動 / web、含 realtime 與 offline）與 Datastore mode（server 端、相容舊 Datastore）

傳統定位：Firebase 行動 app 與 SPA 的後端資料層、MVP 快速驗證期、多裝置即時同步的產品。

資料層視角的定位：一塊 managed serverless document store，把 capacity、replication、failover、scaling 全部交給平台，代價是查詢能力與資料模型沿平台特性生長。

資料形狀與查詢邊界

Firestore 為「已知路徑的 document 讀寫」付成本，不為「任意欄位的 ad-hoc 查詢」付成本。這個取向決定了它的甜蜜區與牆：

• 單 document 與單 collection 內的 key-based / 條件查詢高效，且每筆查詢都要有對應 index（單欄 index 自動建立、複合查詢要建 composite index）
• 查詢結果集的計費與大小跟「讀了幾筆 document」成正比，不是跟「掃了多少」— 一次回 10,000 筆就計 10,000 次 read
• 缺少 server 端 aggregation pipeline 與 JOIN；跨集合報表（例如「本月各地區訂單金額」）在 Firestore 上要嘛預先把彙總寫成一份 document、要嘛把資料複製到分析系統
• 沒有原生全文搜尋，全文需求要接專門的 search index（Algolia、Elasticsearch / OpenSearch）

這條查詢邊界是 Firestore 最容易被低估的設計約束。它不是「功能還沒做」，而是 client 直連 + serverless 計費模型的必然結果：把任意 ad-hoc 查詢開放給前端，等於把不可預測的成本與掃描壓力暴露在公網。建模時要先窮舉 access pattern、再決定 document 結構，跟 DynamoDB single-table design 的 access-pattern-first 思路同源。

一致性、realtime 與容量特性

一致性：

• 單 document 讀寫與「查詢結果在同一 region 內」提供 strong consistency
• 多 region 部署靠平台複製、跨 region 讀取可能有延遲；一致性語意由平台決定、不可調到自管資料庫那種 isolation level 顆粒

Realtime 與 offline：

• snapshot listener 讓 client 訂閱 query 結果、資料變更即時推送，是多裝置同步的核心能力
• 行動 / web SDK 內建 offline persistence，斷線時讀寫本地快取、回線後同步，這是自建 REST API 要額外工程才有的能力

容量與寫入熱點：

• serverless 自動擴縮，無 connection 概念，前端裝置數不直接轉成資料庫連線壓力
• 單一 document 的高頻寫入會撞到 contention（官方建議單 document 的持續寫入維持在每秒個位數量級、高頻計數器要用 distributed counter 分片）
• 寫入吞吐與索引維護成本綁在一起：每多一個 index、寫入就多一份維護成本

容量特性的時間敏感數字（每秒寫入軟上限、單 document contention 門檻）以 官方 best practices 為準，設計高頻寫入前先查當前限制。

適用場景

1. 行動 app / SPA 的 MVP 後端：

• 認證接 Firebase Auth、資料存 Firestore、推播接 Cloud Messaging，整個 MVP 沒有自己的後端服務
• 對應 0.21 BaaS 段的「把後端工程師這個角色延後」

2. 多裝置即時同步：

• 協作筆記、聊天、即時看板這類「一處改、多處即時更新」的產品
• snapshot listener + offline persistence 是這類需求的天然形狀

3. access pattern 穩定的 document 工作負載：

• user profile、設定、feed item、活動紀錄這類讀多寫少、查詢路徑固定的資料
• 跟 source of truth 對齊：Firestore 可以是這些資料的正式狀態

不適用場景

1. 跨實體報表與分析查詢：

• 跨 collection JOIN、ad-hoc 篩選、彙總統計在 Firestore 上要靠資料複製工程
• 替代：自建 relational（PostgreSQL）或把資料同步進分析系統

2. 成本對流量敏感的高讀取場景：

• 計費隨 document read / write / delete 線性成長，高流量下可能超過自建
• 替代：自管資料庫 + 應用層 cache，把熱讀取的單位成本壓下來

3. 複雜授權需要可測試的控制面：

• client 直連模型把授權全塞進 Security Rules，規則長到難以 review / 測試時，控制面風險升高
• 替代：把授權拉回後端 API 中介層（自建後端 + 任意資料庫）

4. 強一致的多實體交易：

• Firestore 有 transaction 與 batch write，但跨大量 document 的複雜交易不是它的主場
• 替代：relational database 的多表交易

跟其他 vendor 的取捨

vs MongoDB（document 對 document）：

• Firestore：serverless、client 直連、realtime listener、GCP / Firebase 綁定、查詢能力受限
• MongoDB：查詢與 aggregation 彈性高、跨雲、要自管或用 Atlas managed、走後端中介存取
• 選 Firestore：行動 / 即時同步 / 想省整層後端
• 選 MongoDB：document model 但要彈性查詢、aggregation、跨雲可攜，見 db3 vendor selection

vs DynamoDB（serverless NoSQL 對 serverless NoSQL）：

• Firestore：GCP / Firebase 生態、內建 realtime 與 offline、client 直連為主
• DynamoDB：AWS 生態、access-pattern-first KV、通常走後端整合、streams 接事件驅動
• 兩者的 access-pattern-first 建模思路相近，差別在生態與 client 直連的有無

vs SQLite（行動端的反向選擇）：

• Firestore：雲端 store、自動多裝置 sync、realtime
• SQLite：embedded、offline-first、無 sync（見 SQLite vendor）
• 選 Firestore：需要跨裝置同步與即時更新
• 選 SQLite：純單機 / offline、不需要雲端同步

vs Supabase（BaaS bundle 的另一條路）：

• Firestore：document model、Google 的 BaaS bundle 資料層
• Supabase：底層是 PostgreSQL（relational）、開源 BaaS bundle，遷出時資料是標準 SQL
• 兩者都是 client 直連 + 規則授權的 BaaS 形狀，差別在資料模型（document vs relational）與遷出時的資料可攜性；Supabase 的資料層判讀見 Managed PostgreSQL 比較，選型層錨點見 0.22

容量規劃要點

1. access pattern 先於 document 結構：

• 列出 application 對資料的所有讀寫路徑、再設計 collection / document 形狀
• access pattern 沒想清楚就建模，後面報表查不出來要重做

2. 反正規化換查詢效率：

• 為了避免跨 collection 多次查詢，常把關聯資料冗餘寫進同一 document
• 代價是寫入時要維護多份副本的一致性，對應 1.9 Reconciliation

3. index 與寫入成本綁定：

• 複合查詢要先建 composite index、否則查詢直接失敗
• 每個 index 增加寫入維護成本，移除用不到的 index 是容量優化的一環

4. 高頻寫入用 distributed counter：

• 單一 document 撞到 contention 上限時，把計數拆成多個 shard document 再彙總

5. 成本以 document 數計，不以掃描量計：

• 容量估算要算「每個畫面 / API 觸發幾次 read」、乘上日活與頻率
• 把熱讀取移到 應用層快取 是壓低 read 計費的主要手段

常見陷阱

• 把 Firestore 當關聯式用：規劃了一堆需要 JOIN 的 collection、上線後跨集合查詢全靠 client 自己組、latency 與 read 成本爆炸
• 報表需求到了才發現查不出來：老闆要月報、Firestore 沒有 aggregation pipeline、被迫臨時搭資料複製管線
• Security Rules 長到沒人敢改：授權全寫在規則 DSL、沒有版本控制與測試、變更時靠人工推敲
• 單 document 當高頻計數器：直播按讚 / 即時計數寫爆單一 document 的 contention 上限
• 忽略 read 計費規模：list 畫面一次回上千筆、每次重整都計上千次 read、帳單月底才浮現

Deep article 章節群

Firestore overview 負責第一輪服務判斷；vendor 特有機制的設定、踩坑與容量規劃拆成 deep article。下表是目前已建立的實作層教材，讀法是先讀 overview 判斷服務適配，再按撞到的壓力選 deep article。

讀法路由：撞到資料外洩 / 越權，讀 Security Rules；撞到熱門事件寫爆計數，讀 distributed counter；改一筆要連動改一千筆，讀反正規化；即時功能帳單失控，讀 realtime listener。撞到報表 / 成本 / 授權整體性的牆，走 遷往自建 relational。

Hands-on 操作演練

deep article 講機制判讀，Hands-on 操作路線 把機制轉成可在本地 Firebase Emulator 跑的演練——零雲端成本、可重跑、產出可驗證 artifact。三個 lab：emulator quickstart（建立共用環境）、Security Rules test lab（規則自動化測試 + 接 release gate）、distributed counter lab（分片計數機制驗證）。lab 全程標明 emulator 驗得了什麼（功能行為、規則求值）、驗不了什麼（計費、寫入軟上限要回雲端）。

已知 limitation 與後續路由

Firestore overview 完成服務判斷、資料形狀、查詢邊界與替代路由；deep article 章節群覆蓋授權、高頻寫入、反正規化與即時同步四個機制；hands-on 章節群提供 emulator 演練。後續可補的方向：offline persistence 的衝突解決深入、realtime listener 在雲端的成本量測 lab（emulator 不計費、要在雲端 staging 跑）。

下一步路由

• 完整 T1 對照：01-database vendors index
• 同類對比：MongoDB vendor（彈性查詢 document）/ DynamoDB vendor（access-pattern-first KV）/ db3 vendor selection（document / KV / multi-model 三方選型）
• 遷出方向：Firestore → 自建 relational（撞到報表 / 成本 / 授權牆後的 Type E 重建模 playbook）
• 操作演練：Firestore Hands-on（emulator quickstart、Security Rules 測試、distributed counter lab）
• 容量背景：1.10 KV / Document DB 容量規劃
• 選型上層：0.21 交付形態選型 / 0.22 能力級買 vs 建 / BaaS 知識卡
• 從託管平台遷出的資產線盤點：10.3 託管形態遷出
• 官方：Firestore documentation、Firestore best practices、Firestore pricing

本文是 Firestore overview 的 migration playbook。寫作參照 Migration Playbook 寫作方法論。BaaS 託管平台整場遷出的資產線盤點與並行期總覽見 10.3 託管形態遷出；本文聚焦資料層的跨 paradigm 重建模。

「我們把 Firestore 整包匯出，匯進 PostgreSQL 就好。」這句話低估了遷移的真正內容 — Firestore 遷往自建 relational 的難點是反轉整個存取模型，搬資料只是其中最容易的一條線。Firestore 是 client 用 SDK 直連資料庫、授權寫在 Security Rules；自建 relational 是 client 打自己的後端 API、授權在後端中介層。資料可以匯出，但反正規化的 document 形狀、沿查詢限制長出來的資料模型、realtime listener 與 offline 同步能力，都沒有 1:1 的對應物。字面意義的「匯出再匯入」只搬走了最容易的那部分。本文走 paradigm shift 結構：先講為何字面遷移不成立、再講哪些該遷哪些先留、最後才是階段化執行。

遷移的 driver：三面牆，不是「relational 比較好」

Firestore 遷往自建很少因為「relational 比較好」這種空泛動機，而是撞到 0.21 BaaS 段描述的三面具體的牆。先確認 driver 真的成立、再啟動遷移：

No-go condition：產品仍以多裝置 realtime 同步與 offline-first 為核心賣點、且查詢需求簡單、成本仍在舒適區 → 先不要遷。這些正是 Firestore 的主場，硬遷會把 realtime / offline 這層平台白送的能力變成自己要重建的工程。遷移前先問「撞的是哪面牆」，三面牆都沒撞到就是 0.22 講的偽自建。

逐能力遷出是常態而非整包搬離：0.22 的「成長期 SaaS」例子 就是只把撞牆的資料層搬到自管 PostgreSQL、認證留在原平台。本文預設的也是這種逐能力遷出 — 遷的是資料層，不一定連認證、儲存一起搬。

6 維 diff audit：主導維度是 paradigm + application change

遷移前先盤點 source 跟 target 的差異落在哪幾維、決定 playbook 結構：

主導維度是 paradigm 與 application change：六維裡五維落在 High。這定義了結構 — Type E paradigm shift（排除 schema 翻譯 Type A 和 drop-in Type B）：存取模型反轉、部分能力重建、可能長期混合（資料層自建、認證仍留平台）。

為什麼字面遷移不成立：存取模型反轉

Firestore 的存取模型是 前端即客戶端、資料庫直接面向公網、授權在規則層；自建 relational 是 前端打後端、後端面向資料庫、授權在服務層。這個反轉是遷移的核心難點，不在資料搬運。

反正規化 document → 正規 schema：

• Firestore 為了繞開查詢限制，常把關聯資料冗餘寫進同一 document（一份資料複製多處）
• 遷往 relational 要把冗餘拆回正規化 table、重建外鍵關係，這是逆向工程：要先讀懂當初為什麼這樣存
• 反過來說，有些 document 的巢狀結構在 relational 用 JSONB 保留更省事（見 PostgreSQL jsonb）— 不是所有 document 都要拆成 table

Security Rules 授權 → 後端授權：

• Firestore 的授權邏輯散在 Security Rules DSL 裡，遷移要把每一條規則翻譯成後端 API 的權限檢查
• 這層翻譯是安全敏感的：漏一條規則等於開一個越權查詢的洞，對應 1.5 資料層紅隊

SDK 直連 → API 中介：

• 前端原本用 Firestore SDK 直接讀寫，遷移後要拔掉 SDK、改打自建 API
• 這是 application 層的大改，不是資料庫換連線字串

realtime listener / offline persistence → 自己重建：

• snapshot listener 的即時推送、offline 讀寫快取，是平台白送的能力
• 自建要用 WebSocket / SSE 重建即時層（見 03 訊息佇列 與 presence 設計）、用前端本地儲存重建 offline — 這是遷移最容易被漏估的工作量

所以遷移的第一步不是匯資料，是盤點 application 對 Firestore 的所有依賴面：查詢路徑、授權規則、realtime 訂閱、offline 行為。這份清單決定哪些能直接遷、哪些要重建、哪些先留在平台。

哪些該遷、哪些先留（逐能力混合）

Type E 的本質是不收斂 — 不必把所有 Firebase 能力一次搬完。判讀標準：

0.22 的成長期 SaaS 是這個判讀的 case anchor：撞牆的是資料層的 query 複雜度與成本，遷的就是資料層，認證留在原地。混合不是過渡失敗，是逐能力選型的穩態。

Phase plan：存取模型反轉的階段化

paradigm shift 的階段化把不可逆動作放到最後、每階段有獨立驗證門檻：

Phase 1：依賴面盤點

列出 application 對 Firestore 的所有讀寫路徑、Security Rules 授權條件、realtime 訂閱點、offline 行為。標每項的頻率、安全敏感度、是否可重建。這份清單不完整不進下一階段。

Phase 2：relational 重建模

把反正規化 document 設計回正規 schema、決定哪些巢狀結構用 JSONB 保留。同步設計後端 API 的端點與授權檢查、把 Security Rules 逐條翻譯成服務層權限。對應 1.2 schema design 與 1.5 資料層紅隊。

Phase 3：自建後端 + dual-write

立起自建後端 API 與資料庫，前端關鍵寫入路徑同時寫 Firestore 與新後端。Firestore 仍是 source of truth、新庫累積資料。dual-write 要處理一邊失敗的補償（對應 1.9 Reconciliation）。

Phase 4：backfill 歷史資料

把 Firestore 既有 document 按新 schema 轉換寫入新庫。backfill 與 dual-write 並行時要處理覆蓋順序，backfill 不能蓋掉 dual-write 的新值。轉換過程記 checksum / row count 對照。

Phase 5：shadow read 驗證

讀路徑同時打 Firestore 與新後端、比對結果、記錄差異但仍以 Firestore 回應用戶。差異率降到可接受才進 cutover。對應 1.7 Schema Migration Rollout 證據 的 evidence 方法。

Phase 6：漸進 cutover + 重建即時層

前端逐步把讀寫從 Firestore SDK 切到自建 API（按比例 / 按功能模組），保留切回能力。若產品需要 realtime，這階段要把 snapshot listener 換成自建即時層（WebSocket / SSE）並驗證延遲與斷線重連。cutover 完成後資料層的 source of truth 轉到自建；未遷的能力（認證、儲存）仍在平台 — 混合架構成立。

Evidence：每階段的前進依據

每個階段用資料證明可前進、不靠感覺：

這些 evidence 對齊 4.20 Observability Evidence Package（Source / Time range / Query link / Owner / Data quality）與 6.8 release gate。授權翻譯這項要特別當成 gate 條件 — 它是安全邊界、不只是功能正確性。

Cutover 與 rollback 決策

資料庫切流失敗代價高、加上這裡牽涉授權正確性，決策權責要寫清楚：

• cutover window：選低流量時段、明確切流比例階梯（如 1% → 10% → 50% → 100%），按功能模組切比按全站切安全
• rollback condition：新 API error rate / latency 超閾值、shadow read 差異率異常、或發現授權翻譯漏洞 → 切回 Firestore
• decision owner：誰有權喊停、依據什麼 evidence、記錄在 8.19 incident decision log
• realtime 連續性：若即時層同步切換，要驗證切換期間訂閱不中斷、或明確告知短暫降級

對應 rollback window、rollback condition。

Cleanup 與長期混合

Type E 的 cleanup 通常不是「關掉整個 Firebase」— 多數情況認證、儲存仍留平台：

• 已遷資料路徑的 Firestore collection、Security Rules、dual-write code path 退役
• shadow read 比對 code 移除
• 前端殘留的 Firestore SDK 依賴清掉（資料層已不走它）
• 但 Firebase Auth / Storage 若仍在用，保留；明確標示哪條資料路徑的 source of truth 是自建庫、哪條仍在平台
• Firestore 的資料匯出備份保留到確認新庫穩定，對應 10.3 的並行期退役判準

混合架構不是遷移失敗、是逐能力選型的穩態 — 撞牆的資料層自建、沒撞牆的認證 / 儲存留在平台。

失敗模式

production 常見的 5 個踩雷：

Case 1：只匯資料、漏了存取模型反轉

把 Firestore 匯出匯進 PostgreSQL 就以為遷完、忘了前端還在打 SDK、授權還在 Security Rules。修法：依賴面盤點是 Phase 1、資料搬運只是其中一條線，存取模型反轉才是主體。

Case 2：Security Rules 翻譯漏洞

把規則翻成後端授權時漏一條、開了越權查詢的洞、上線後資料外洩。修法：授權翻譯要逐條對照 + 紅隊驗證（1.5）、當成 cutover gate 條件、不是功能 bug。

Case 3：反正規化還原錯誤

document 的冗餘副本拆回 table 時還原錯關係、新庫資料關聯接錯。修法：Phase 2 先讀懂當初為何反正規化、backfill 後抽查還原正確性、shadow read 比對抓出建模差異。

Case 4：低估 realtime / offline 重建工作量

以為遷資料庫就好、上線才發現 snapshot listener 與 offline 同步整層要自己重建、進度爆炸。修法：依賴面盤點就把 realtime 訂閱點與 offline 行為標出來、列入工作量、必要時這層最後遷或先保留。

Case 5：dual-write 一邊失敗沒補償

dual-write 時新庫寫成功 Firestore 失敗（或反之）、兩邊分歧、cutover 後資料不完整。修法：dual-write 要有失敗補償（記錄、重試、標記人工對帳），對應 1.9 Reconciliation。

Anti-recommendation：產品仍重度依賴 realtime / offline、或團隊還沒有自建後端與資料庫的營運能力（backup、failover、授權設計）→ 先不要遷。可先把一塊撞牆最明顯、realtime 需求最低的資料（例如報表來源資料）試點、累積自建營運經驗再擴大。

容量與成本：crossover 判讀

遷移的成本判讀關鍵是 遷移後的總帳、不是只看 Firestore 帳單：

• 遷移當下：高 read 流量下，自管資料庫 + 應用層快取的單位成本常低於 Firestore 的 per-read 計費
• 但要加回自建的隱性成本：後端服務的開發與維運、資料庫的 backup / failover / 擴容、realtime 層的重建與維護、團隊人力
• 判讀分層：撞到成本牆且已有後端團隊 → 自建總帳通常划算；仍是小團隊、realtime 是核心、流量不大 → Firestore 的「平台白送能力」可能仍比自建總帳便宜

Scope warning：crossover 隨流量形狀、region pricing、團隊成本結構變動、無通用閾值。遷移省下的 Firestore 帳單要扣掉自建後端 + 資料庫 + 即時層的維運成本後再比，不是直接拿兩邊資料庫帳單對照。

接回 0.6 成本、風險與選型取捨、1.10 KV / Document DB 容量規劃。

邊界與整合

跟其他遷移路徑的關係

• 保留 document model：若只是要逃離 Firestore 的查詢限制、但 document 形狀仍適合，遷 MongoDB 比遷 relational 的 paradigm 跨度小、不必反正規化還原
• 整包託管遷出：若連認證、儲存一起搬離 Firebase，整場資產線盤點與並行期走 10.3 託管形態遷出、本文是其中資料層那一條
• 反向視角：哪些資料當初就不該進 Firestore（報表來源、強一致交易），見 Firestore overview 的不適用場景

Sibling 與 cross-link

• Firestore overview — 服務定位與查詢邊界
• 1.6 資料庫轉換實作 — 通用 dual-write / shadow read / cutover 框架
• 1.5 資料層紅隊 — Security Rules 授權翻譯的安全驗證
• 1.9 Reconciliation 與 Data Repair — dual-write 失敗補償與資料對帳
• 從 RDS / MongoDB 遷往 DynamoDB — 同為 Type E paradigm shift 的對照（方向相反：遷入 NoSQL vs 遷出 BaaS）
• 0.21 交付形態選型 / 0.22 能力級買 vs 建 — 遷移 driver 的選型層背景

本文是 Firestore overview 的 deep article。寫作參照 Vendor 深度技術文章寫作方法論。規則語法以 官方 Security Rules 文件 為準、最後檢查日 2026-06-16。

問題情境：授權沒有後端可以藏

自建後端的授權有一個天然的藏身處：所有讀寫都過 API，權限檢查寫在 service 層，前端拿不到的資料就是拿不到。Firestore 的 client 直連模型把這個藏身處拿掉了——前端 SDK 直接連資料庫，唯一擋在「任何人都能讀整個 collection」與「正確授權」之間的，就是 Security Rules。規則寫錯一條，等於把資料庫對公網敞開。

這個責任轉移最常見的引爆點是上線後的滲透測試或 bug bounty：報告指出「未登入就能用 REST API 拉出整張 users collection」。根因幾乎都是同一類——開發期為了方便把規則設成 allow read, write: if true，上線忘了收。Firestore 的規則是控制面的全部，這篇處理它的求值模型、如何把它寫成可測試的程式碼、以及它撐不住時的退場路線。

核心概念：規則的求值模型

Firestore Security Rules 是一套宣告式 DSL，掛在 match path 上、對每個讀寫請求求值。理解它要抓住四個跟後端授權不同的點：

規則不是 filter，是 allow/deny 判定。一條 allow read: if <condition> 不會「只回傳符合條件的 document」——它是對「這次請求能不能執行」的布林判定。query 若可能讀到任何不符合規則的 document，整個 query 被拒絕，不是默默過濾。這逼著 client 的 query 必須自帶與規則一致的條件（例如 where('ownerId', '==', uid)），規則才放行。

規則預設拒絕。沒有 match 命中的 path 一律拒絕。rules_version = '2' 下，match /{document=**} 遞迴匹配所有 subcollection，要小心別用一條寬鬆的遞迴規則蓋掉底下該嚴格的 path。

請求脈絡來自 request 與 resource。request.auth 是已驗證的身分（request.auth.uid、request.auth.token 的 custom claims）；request.resource.data 是寫入後的 document 狀態；resource.data 是寫入前的既有狀態。授權與資料驗證都在這幾個物件上展開。

跨 document 查詢用 get() / exists()。判斷「這個 user 是不是這個 project 的成員」要去讀另一份 document，用 get(/databases/$(database)/documents/projects/$(pid)/members/$(uid))。每個 get() 是一次額外讀取、計入計費，也有每請求次數上限（規則內 document access 有上限，設計時要省著用）。

基本骨架：

 1rules_version = '2';
 2service cloud.firestore {
 3  match /databases/{database}/documents {
 4    match /notes/{noteId} {
 5      allow read: if request.auth != null
 6                  && resource.data.ownerId == request.auth.uid;
 7      allow create: if request.auth != null
 8                    && request.resource.data.ownerId == request.auth.uid;
 9      allow update, delete: if request.auth != null
10                            && resource.data.ownerId == request.auth.uid;
11    }
12  }
13}

read 用 resource.data（既有 document），create 用 request.resource.data（沒有既有狀態），update 兩者都要看——把 read / create / update / delete 分開是建模的起點，混成一條 allow read, write 是後面所有漏洞的源頭。

配置：把授權拆成可組合 function

規則一旦超過幾個 collection，inline 的 if 條件會重複且難讀。把授權判斷抽成 function，讓每條規則讀起來像在描述意圖，是讓規則可維護的核心手段：

 1rules_version = '2';
 2service cloud.firestore {
 3  match /databases/{database}/documents {
 4
 5    function isSignedIn() {
 6      return request.auth != null;
 7    }
 8
 9    function isOwner(docData) {
10      return isSignedIn() && docData.ownerId == request.auth.uid;
11    }
12
13    function isProjectMember(projectId) {
14      return isSignedIn()
15        && exists(/databases/$(database)/documents/projects/$(projectId)/members/$(request.auth.uid));
16    }
17
18    function hasRole(projectId, role) {
19      return isProjectMember(projectId)
20        && get(/databases/$(database)/documents/projects/$(projectId)/members/$(request.auth.uid)).data.role == role;
21    }
22
23    // 寫入時欄位白名單：禁止 client 竄改 ownerId / createdAt
24    function fieldsUnchanged(fields) {
25      return request.resource.data.diff(resource.data).affectedKeys().hasOnly(fields);
26    }
27
28    match /projects/{projectId} {
29      allow read: if isProjectMember(projectId);
30      allow update: if hasRole(projectId, 'admin')
31                    && fieldsUnchanged(['name', 'description', 'updatedAt']);
32      allow delete: if hasRole(projectId, 'owner');
33
34      match /tasks/{taskId} {
35        allow read: if isProjectMember(projectId);
36        allow create: if isProjectMember(projectId)
37                      && request.resource.data.createdBy == request.auth.uid;
38        allow update, delete: if isProjectMember(projectId);
39      }
40    }
41  }
42}

這裡有三個建模手段值得展開。第一，isProjectMember / hasRole 把「成員資格」與「角色」的判斷集中成單一定義，授權邏輯改一處全站生效，避免同一條規則散落在十個 collection。第二，fieldsUnchanged 用 diff().affectedKeys().hasOnly() 把「這次 update 只准動哪些欄位」寫成白名單——這擋掉 client 直接改 ownerId 把別人的資料佔為己有的攻擊，是 client 直連模型必備的欄位級防護。第三，custom claims（request.auth.token.role）適合放跨專案、低頻變動的全域角色；per-resource 的成員資格用 get() 查 membership document，因為 claims 改動要等 token 刷新、不適合表達即時變動的權限。

配置：用 emulator 把規則寫成單元測試

規則是安全邊界，改一條就要驗證沒開新洞——這要求規則像程式碼一樣有測試。Firebase Emulator + @firebase/rules-unit-testing 讓規則在本地用真實求值引擎跑斷言，不必碰雲端：

 1// rules.test.js — 用 Jest / Mocha 跑
 2const {
 3  initializeTestEnvironment,
 4  assertFails,
 5  assertSucceeds,
 6} = require('@firebase/rules-unit-testing');
 7const { setDoc, getDoc, doc } = require('firebase/firestore');
 8
 9let testEnv;
10
11beforeAll(async () => {
12  testEnv = await initializeTestEnvironment({
13    projectId: 'demo-notes',
14    firestore: { rules: require('fs').readFileSync('firestore.rules', 'utf8') },
15  });
16});
17
18afterAll(async () => { await testEnv.cleanup(); });
19beforeEach(async () => { await testEnv.clearFirestore(); });
20
21test('owner 能讀自己的 note', async () => {
22  // 用 admin context 預先種一筆資料、繞過規則
23  await testEnv.withSecurityRulesDisabled(async (ctx) => {
24    await setDoc(doc(ctx.firestore(), 'notes/n1'), { ownerId: 'alice' });
25  });
26  const alice = testEnv.authenticatedContext('alice').firestore();
27  await assertSucceeds(getDoc(doc(alice, 'notes/n1')));
28});
29
30test('非 owner 不能讀別人的 note', async () => {
31  await testEnv.withSecurityRulesDisabled(async (ctx) => {
32    await setDoc(doc(ctx.firestore(), 'notes/n1'), { ownerId: 'alice' });
33  });
34  const bob = testEnv.authenticatedContext('bob').firestore();
35  await assertFails(getDoc(doc(bob, 'notes/n1')));
36});
37
38test('未登入完全擋下', async () => {
39  const anon = testEnv.unauthenticatedContext().firestore();
40  await assertFails(getDoc(doc(anon, 'notes/n1')));
41});
42
43test('client 不能竄改 ownerId', async () => {
44  await testEnv.withSecurityRulesDisabled(async (ctx) => {
45    await setDoc(doc(ctx.firestore(), 'notes/n1'), { ownerId: 'alice', text: 'hi' });
46  });
47  const alice = testEnv.authenticatedContext('alice').firestore();
48  await assertFails(setDoc(doc(alice, 'notes/n1'), { ownerId: 'bob', text: 'hi' }));
49});

啟動方式 firebase emulators:exec --only firestore "npm test"，讓測試在 CI 跑。測試要覆蓋的不只是 happy path——每條規則至少要有「正向放行」「越權拒絕」「未登入拒絕」「欄位竄改拒絕」四類斷言。assertFails 比 assertSucceeds 更重要：它證明的是「該擋的有擋住」，正是滲透測試會打的點。把這套測試接進 release gate，規則變更才有 evidence 可交（對應 6.8 release gate）。

故障演練：五個把規則寫成漏洞的 production 踩坑

Case 1：allow read, write: if true 上線沒收

開發期為了快，把規則開全放，上線忘改。任何人用公開的 project config（前端 bundle 裡就有）就能 REST 拉整個資料庫。修法：規則預設從 deny 起手，開發期的寬鬆規則進不了 main branch；CI 跑一條 lint 掃 if true，命中即 fail。這是 1.5 資料層紅隊 越權查詢路徑的最便宜目標。

Case 2：read 沒拆 get 與 list

allow read 同時涵蓋讀單一 document（get）與查整個 collection（list）。規則只想開「讀自己那筆」，卻因為沒拆 list，讓 client 能 list 整個 collection 撈別人的資料。修法：對 collection-level query 敏感的 path，把 read 拆成 allow get 與 allow list，list 條件更嚴或直接關閉、改走後端彙整。

Case 3：信任 request.resource.data 的內容沒驗證

create 規則只檢查 request.auth != null，沒驗證寫入內容。client 自己塞 role: 'admin' 或 balance: 999999 進 document。修法：寫入規則要驗證關鍵欄位的值與型別（request.resource.data.role == 'member'、request.resource.data.amount is int），敏感欄位（角色、金額、狀態）的權威值不該由 client 寫入、改由 Cloud Function 或後端寫。

Case 4：遞迴 match /{document=**} 蓋掉嚴格規則

頂層放一條 match /{document=**} { allow read: if isSignedIn(); } 圖方便，結果它遞迴命中所有 subcollection，把底下本來該按成員資格嚴格控管的 members collection 也開成「登入即可讀」。修法：避免寬鬆的遞迴萬用規則；授權顆粒不同的 path 各自寫明確 match。

Case 5：規則複雜到沒人能 review

授權邏輯長到幾百行、巢狀 get() 互相依賴，改一條沒人敢保證沒開新洞、也沒有測試。修法：這是規則撐不住的訊號（見下方邊界段）——超過這個複雜度，授權該拉回後端中介層，而不是繼續在 DSL 裡長。

容量與觀測：get() 計費與規則複雜度上限

規則內的每個 get() / exists() 是一次 document 讀取，計入計費，且單次請求的 document access 有數量上限（以 官方限制 為準）。高頻讀取路徑若每次都 get() 查 membership，成本與延遲都會浮現。優化方向有二：把低頻變動的權限（全域角色）放進 custom claims，從 token 直接讀、零額外 document access；把成員資格設計成可由 document path 直接判斷（例如 membership document 的 ID 就是 uid，用 exists() 而非 get() 撈整份）。

觀測上，授權問題不會在規則層留下豐富 log——被拒的請求 client 端收到 permission-denied。要把這類錯誤從 client 回報、或在關鍵寫入路徑改走 Cloud Function 以取得 server 端 audit log，接回 7.7 稽核軌跡。規則本身的變更要進版本控制、每次 deploy 留 diff，授權變更才可回溯。

邊界與整合：規則撐不住時把授權拉回後端

Security Rules 適合表達「資源的擁有者與成員能做什麼」這類 resource-scoped 授權。它撐不住的訊號很明確：授權依賴跨多個 document 的複雜聚合判斷、需要呼叫外部系統、規則複雜到無法 review、或業務規則頻繁變動到規則 deploy 跟不上。撞到這些訊號時，正確的動作是把該塊授權移出 client 直連路徑，而非把規則寫得更巧：

• 敏感寫入改走 Cloud Function / 後端 API：金額、狀態機轉換、跨實體一致性的寫入，由 server 端驗證後以 admin 權限寫入，規則對 client 直接關閉這些 path 的寫入
• 複雜授權整體下沉：當規則複雜度本身成為風險，這是 Firestore → 自建 relational playbook 裡「授權控制面失控」這面牆——把授權拉回後端中介層是遷移的 driver 之一

判讀的單位仍是逐路徑：簡單的 owner-scoped 資料留在規則 + client 直連，複雜或敏感的部分走後端。不是非此即彼。

下一步路由

• 上層：Firestore overview（服務定位與查詢邊界）
• 安全驗證：1.5 資料層紅隊（越權查詢與資料外洩路徑）
• 遷移 driver：Firestore → 自建 relational（授權控制面失控的退場）
• 發布證據：6.8 release gate（規則測試接進 gate）
• 官方：Security Rules get started、Rules unit testing、Rules conditions limits

本文是 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 overview 的 deep article。寫作參照 Vendor 深度技術文章寫作方法論。

問題情境：改一個使用者名稱要改一千筆

一個社群 app 的貼文列表要顯示作者頭像與名稱。關聯式思路是貼文存 authorId、查詢時 JOIN users 表。但 Firestore 沒有 JOIN——要嘛 client 每顯示一則貼文就多查一次 users（列表 20 則就 20 次額外讀取），要嘛在貼文 document 裡直接存一份 authorName 與 authorAvatar 副本。為了讀取效率，多數人選後者。

副本一上線就埋了一致性債：使用者改了名稱，他過去發的一千則貼文裡的 authorName 還是舊的。改名這個動作從「更新一筆 users document」變成「更新一千筆貼文 document」。這篇處理 Firestore 反正規化的建模決策、如何用 fan-out write 維護副本一致、以及這套手段撐不住時的退場。

核心概念：反正規化是查詢邊界逼出來的

關聯式資料庫預設正規化，靠 JOIN 在查詢時組合資料；Firestore 沒有 server 端 JOIN，組合資料只有兩條路：client 多次查詢自己組，或寫入時就把要一起讀的資料存在一起。後者就是反正規化——它不是 Firestore 的「壞習慣」，是 client 直連 + 無 JOIN 的查詢模型逼出來的必然建模。

反正規化的判斷單位是 access pattern，不是資料的「正規與否」。問題不是「該不該複製」，而是「這份資料在哪些讀取路徑上要被一起讀到，複製它的一致性維護成本，比每次多查一次划不划算」。判斷有三個輸入：

讀寫比。讀多寫少的資料適合反正規化——複製成本攤在少數寫入上、省下大量讀取的額外查詢。作者名稱顯示在每則貼文（高讀），但改名很少（低寫），複製划算。反過來，高頻變動的資料複製多份，每次變動要 fan-out 到所有副本，成本可能超過省下的讀取。

副本數量的可預測性。複製到「一個 user 的 profile 摘要」這種固定副本可控；複製到「該 user 的所有貼文」這種隨資料成長無上限的副本，fan-out 的寫入量會隨規模膨脹，要特別評估。

一致性容忍度。副本短暫不一致（改名後幾秒內舊貼文還顯示舊名）能不能接受。能容忍最終一致的，反正規化的維護可以非同步、用 Cloud Function 慢慢 fan-out；不能容忍的，要嘛同步 fan-out（貴且有規模上限），要嘛這份資料根本不該複製。

配置：fan-out write 維護副本一致

fan-out write 是「一次邏輯更新，寫多個 document」。Firestore 的 writeBatch 讓多個寫入 atomic 提交（最多 500 個操作一批），是固定且可控副本數的標準手段：

 1import { writeBatch, doc, collection, query, where, getDocs } from 'firebase/firestore';
 2
 3// 改名：更新 users/{uid} + fan-out 到該 user 的所有貼文副本
 4async function renameUser(db, uid, newName) {
 5  // 1. 更新權威來源
 6  const userRef = doc(db, 'users', uid);
 7
 8  // 2. 查出所有要同步的副本
 9  const postsSnap = await getDocs(
10    query(collection(db, 'posts'), where('authorId', '==', uid))
11  );
12
13  // 3. batch 提交（超過 500 要分批）
14  const ops = [{ ref: userRef, data: { displayName: newName } }];
15  postsSnap.forEach((p) => {
16    ops.push({ ref: p.ref, data: { authorName: newName } });
17  });
18
19  for (let i = 0; i < ops.length; i += 500) {
20    const batch = writeBatch(db);
21    ops.slice(i, i + 500).forEach((op) => batch.update(op.ref, op.data));
22    await batch.commit();
23  }
24}

這裡的關鍵取捨是同步 fan-out 與非同步 fan-out。上面的同步版本在使用者點「儲存」時就把一千筆貼文改完，使用者等待時間隨副本數成長、且超過 500 要分批多次提交，副本數無上限時會撞到不可接受的延遲。非同步版本把權威來源（users/{uid}）同步更新，副本同步丟給 Cloud Function 在背景慢慢做：

 1// Cloud Function：onUpdate users document 時 fan-out 到副本
 2exports.fanoutUserName = functions.firestore
 3  .document('users/{uid}')
 4  .onUpdate(async (change, context) => {
 5    const before = change.before.data();
 6    const after = change.after.data();
 7    if (before.displayName === after.displayName) return; // 名稱沒變不做
 8
 9    const uid = context.params.uid;
10    const postsSnap = await admin.firestore()
11      .collection('posts').where('authorId', '==', uid).get();
12
13    // 分批 fan-out，背景執行、使用者不等待
14    const docs = postsSnap.docs;
15    for (let i = 0; i < docs.length; i += 500) {
16      const batch = admin.firestore().batch();
17      docs.slice(i, i + 500).forEach((d) =>
18        batch.update(d.ref, { authorName: after.displayName }));
19      await batch.commit();
20    }
21  });

非同步 fan-out 把「使用者體驗的即時性」與「副本的最終一致」分開：權威來源立刻更新、副本最終收斂。代價是中間有一段不一致窗口（改名後到 fan-out 完成前，舊貼文顯示舊名），這對社群 app 的顯示名稱通常可接受。writeBatch 與 transaction 的選擇在這裡也要分清：fan-out 是「寫多個獨立 document、不依賴彼此既有值」用 writeBatch；若更新要依賴讀到的當前值（例如同時扣 A 加 B 且要看當前餘額）才用 transaction，但 transaction 在大量 document 的 fan-out 上不適用。

故障演練：五個副本不一致的 production 踩坑

Case 1：複製了卻沒建 fan-out 路徑

貼文存了 authorName 副本，但改名邏輯只更新 users，沒人寫 fan-out。副本永遠停在建立時的值。修法：反正規化的建模決策必須連同「誰負責同步副本」一起定，複製一份資料就要有對應的 fan-out write 路徑，沒有 fan-out 的副本是一致性債。

Case 2：同步 fan-out 撞到副本數上限

改名時同步更新所有貼文，某個高產出使用者有幾萬則貼文，提交分成幾十批、使用者等了半分鐘還在轉圈、甚至 timeout。修法：副本數無上限的 fan-out 改非同步（Cloud Function 背景做），同步 fan-out 只用在副本數固定且小的場景。

Case 3：fan-out 中途失敗留下部分更新

非同步 fan-out 跑到一半 function 掛了，前 500 筆改了、後面沒改，副本處於半新半舊。修法：fan-out function 要可重入（重跑能補完未完成的），或記錄 fan-out 進度；殘留的不一致由對帳流程掃出修復（對應 1.9 Reconciliation 與 Data Repair）。

Case 4：雙向反正規化造成更新環

A 存 B 的副本、B 也存 A 的副本，改 A 觸發 fan-out 改 B、又觸發 fan-out 改回 A，function 互相觸發成環。修法：反正規化要有明確的權威方向（誰是 source of truth、誰是副本），副本不反向觸發權威來源的更新。

Case 5：把副本當權威來源讀來做判斷

拿貼文裡的 authorName 副本去做權限或業務判斷，而非讀 users 權威來源。副本在不一致窗口內是舊值，判斷出錯。修法：副本只供顯示，任何需要正確性的判斷讀權威來源；明確標示哪個 document 是 source of truth、哪些是顯示副本。

容量與觀測：fan-out 寫入量與不一致窗口

反正規化的容量帳要算 fan-out 的寫入放大。一次邏輯更新放大成 N 次寫入，N 是副本數，這 N 次寫入計入計費。高頻變動 + 高副本數的組合會讓寫入成本失控——這正是判斷「該不該反正規化」的成本面：省下的讀取 vs 放大的寫入。

不一致窗口是要監控的健康指標：權威來源更新到所有副本收斂的延遲。非同步 fan-out 下這個窗口隨副本數與 function 吞吐變動，異常拉長是 fan-out 積壓的徵兆。觀測還要涵蓋 fan-out 失敗率與重試，接回 4.20 Observability Evidence Package。定期跑對帳掃描副本與權威來源的差異，是把潛在不一致從「使用者回報才知道」變成「主動發現修復」，對應 1.9 Reconciliation 的可驗證、可修復、可稽核流程。

邊界與整合：反正規化複雜到該回關聯式

反正規化適合「讀多寫少、副本數可控、能容忍最終一致」的顯示資料。它撐不住的訊號是複製關係長成一張難以追蹤的網——資料被複製到十幾個地方、fan-out 路徑互相依賴、改一個欄位要同步的副本沒人說得清、對帳越來越頻繁。撞到這些訊號時，方向不是把 fan-out 寫得更巧：

• 關聯查詢成為主導需求：當資料的核心價值在「任意關聯與聚合」（報表、跨實體分析），反正規化是在用副本模擬 JOIN，成本與複雜度都不划算。這是 Firestore → 自建 relational 的報表牆——relational 的 JOIN 在查詢時組合，省掉整套副本維護
• 副本維護成本超過查詢省下的成本：高頻變動的資料反正規化，fan-out 放大的寫入成本超過正規化後多查一次的成本，反正規化的前提就不成立
• 巢狀結構保留比拆表更省：相反方向——有些一起讀寫、不需獨立查詢的關聯資料，在 Firestore 用巢狀 map / array 保留在同一 document 反而比拆 collection 簡單，遷到 relational 時用 PostgreSQL JSONB 保留，不是所有東西都要拆成正規表

判讀的起點永遠是 access pattern 與讀寫比，不是「正規化是對的、反正規化是妥協」這種預設立場。在 Firestore 裡反正規化是正解，問題只在它的維護成本何時翻轉。

下一步路由

• 上層：Firestore overview（資料形狀與查詢邊界）
• 資料修復：1.9 Reconciliation 與 Data Repair（副本不一致的對帳與修復）
• 狀態歸屬：1.8 State Ownership 與 Query Boundary（權威來源與派生副本的分辨）
• 遷移 driver：Firestore → 自建 relational（報表牆與反正規化還原）
• 官方：Firestore data model、Batched writes

本文是 Firestore overview 的 deep article。寫作參照 Vendor 深度技術文章寫作方法論。計費模型以 官方 pricing 為準、最後檢查日 2026-06-16。

問題情境：即時很爽，帳單很痛

Firestore 的 snapshot listener 是它最有吸引力的能力——client onSnapshot 訂閱一個 query，資料一變就即時推送，多裝置同步、協作介面幾乎免費得到。團隊很快把所有列表都改成 listener：訊息列表、通知、儀表板計數，全部即時更新，體驗很好。

帳單在用戶量上來後出問題。Firestore 對 listener 的計費規則是——query 結果裡每個被推送的 document 都計一次 read。一個列表有 100 名觀眾各自訂閱、列表變動推送 50 筆，就是 100 × 50 = 5000 次 read。即時的爽感建立在 re-read 計費上，扇出越大、變動越頻繁，成本成乘積成長。這篇處理 listener 的推送與計費模型、如何設計訂閱範圍把成本壓住、以及即時需求超過 listener 能力時的退場。

核心概念：listener 的推送與計費模型

snapshot listener 不是「推送變動的那一筆」這麼簡單。理解它的成本要抓三點：

初次訂閱讀整個結果集，之後讀變動的部分。onSnapshot(query) 第一次觸發時，query 結果的每個 document 計一次 read（跟一次性 getDocs 相同）。之後 query 結果有 document 新增、修改、移出，推送那些變動的 document，各計一次 read。所以 listener 的計費 = 初次結果集大小 + 後續每次變動推送的 document 數。

計費是 per-listener 的。同一個 query 被 N 個 client 各自訂閱，是 N 個獨立 listener，變動推送計 N 次。扇出（同一資料多少人在看）直接乘進成本。這跟自建後端用一個 WebSocket broadcast 推給 N 個連線的模型不同——那裡資料讀一次、推 N 份；Firestore listener 是每個訂閱各自從資料庫讀。

query 範圍決定推送頻率。訂閱一個寬的 query（整個 collection），collection 裡任何符合的 document 變動都推；訂閱窄的 query（只我相關的那幾筆），只有那幾筆變動才推。listener 成本的設計槓桿是「把訂閱範圍縮到 client 真正要即時看到的最小集合」。

 1import { onSnapshot, query, collection, where, orderBy, limit } from 'firebase/firestore';
 2
 3// 寬訂閱：整個 messages collection 任何變動都推（成本失控）
 4const wide = query(collection(db, 'messages'));
 5
 6// 窄訂閱：只訂這個對話的最近 50 則（成本可控）
 7const narrow = query(
 8  collection(db, 'messages'),
 9  where('conversationId', '==', convId),
10  orderBy('createdAt', 'desc'),
11  limit(50)
12);
13
14const unsub = onSnapshot(narrow, (snap) => {
15  snap.docChanges().forEach((change) => {
16    // 只處理變動的部分，不是每次重畫整個列表
17    if (change.type === 'added') { /* ... */ }
18    if (change.type === 'modified') { /* ... */ }
19    if (change.type === 'removed') { /* ... */ }
20  });
21});
22// 畫面離開時務必取消訂閱，否則 listener 與計費持續
23// unsub();

docChanges() 是控制成本與效能的關鍵——它只給「跟上次相比變動的 document」，而不是每次都拿整個結果集重畫。用 limit 把結果集封頂、用 where 把範圍縮到 client 相關，是 listener 成本設計的兩個主要手段。

配置：訂閱範圍與生命週期設計

listener 的成本與效能由訂閱範圍和生命週期決定。三個設計原則：

訂閱跟著畫面生命週期。listener 在畫面進入時建立、離開時 unsubscribe()。最常見的成本洩漏是忘記取消訂閱——使用者切走了，listener 還在背景持續接收推送計費。在元件 unmount、路由切換、app 進背景時取消所有 listener。

用 limit 封頂結果集，配分頁。即時列表只訂最近 N 筆，往前翻歷史用一次性 getDocs 分頁，不訂閱。歷史資料不會變、不需要即時，訂閱它只是白付 re-read。即時的部分小而精，歷史的部分按需一次性拉。

高扇出的即時值改訂閱彙總 document。一萬名觀眾要看同一個即時計數，正解是由後端把彙總值寫進一個 summary document、所有人訂閱那一份，而非各自訂閱原始資料加總。扇出仍是一萬個 listener，但每次變動只推一份小 document，而不是推整個結果集——把推送的 payload 壓到最小。這跟 distributed counter 的 summary 彙總是同一個手段的兩面：那裡解寫入熱點，這裡解讀取扇出。

故障演練：五個 realtime 成本踩坑

Case 1：把不需要即時的列表也做成 listener

歷史訊息、已讀通知、靜態設定全用 onSnapshot，這些資料根本不變或極少變，訂閱它們只是把一次性讀取變成持續掛著的 listener。修法：先問「這個資料 client 在看的時候會不會變、變了要不要立刻看到」，否才用 listener；不變或不需即時的用一次性 getDocs。

Case 2：忘記 unsubscribe 造成 listener 洩漏

路由切換、元件重建時建了新 listener 沒取消舊的，listener 越積越多、計費持續、記憶體也漏。修法：listener 的建立與取消綁死畫面生命週期，用框架的 cleanup hook（React useEffect return、Vue onUnmounted）統一管理，app 進背景時主動斷。

Case 3：訂閱寬 query 被無關變動轟炸

訂了整個 orders collection 想看自己的訂單，結果別人的訂單一變也推給你（雖然規則可能擋讀，但寬 query 本身設計就錯）。修法：query 用 where 縮到 client 相關的最小集合，訂閱範圍與 Security Rules 的授權範圍對齊。

Case 4：每次 snapshot 重畫整個列表

onSnapshot callback 裡拿 snap.docs 整個重建 UI，而不用 docChanges()，列表大時每次推送都重畫、UI 卡頓。修法：用 docChanges() 只處理 added / modified / removed 的增量，UI 做局部更新。

Case 5：高扇出直接訂閱原始資料

直播觀看數讓每個觀眾訂閱原始事件流自己算，扇出 × 結果集大小的 re-read 爆炸。修法：後端彙總寫 summary document，觀眾訂閱 summary 一份，把推送 payload 與 re-read 都壓到最小。

容量與觀測：扇出 × 變動頻率的成本估算

listener 成本估算的公式是 初次訂閱 read + Σ(訂閱數 × 每次變動推送的 document 數)。把它拆開算：高扇出（很多人訂同一資料）× 高變動頻率（資料常變）× 大結果集（每次推很多筆）三者相乘，是成本爆炸的組合；任一維壓低都有效。設計時對每個 listener 問這三維的量級，乘起來對照預算。

連線數也有規模考量：Firestore 對並行連線與 listener 有規模上限（以官方當前限制為準），超大扇出（百萬級同時在線）會撞到連線層的天花板，而不只是計費問題。觀測上要監控 read 用量的來源拆分——哪些 collection 的 read 來自 listener 推送、哪些來自一次性查詢，把 listener 的 re-read 成本獨立出來看，接回 4.20 Observability Evidence Package 與 9.7 成本邊界。

邊界與整合：即時需求超過 listener 該換推送架構

snapshot listener 適合「中等扇出、client 要即時看到自己相關資料變動」的場景——協作編輯、聊天、個人通知、儀表板。它撐不住的訊號是扇出或變動頻率推高 re-read 成本到不划算，或連線規模撞到天花板：

• 超高扇出的廣播：百萬人看同一場直播的即時數據，per-listener 的 re-read 模型成本遠高於自建一次讀取、WebSocket broadcast 推 N 份的模型。這類純廣播（一份資料推給海量訂閱者）用專門的推送層（自建 WebSocket / SSE、或 pub/sub + 邊緣推送）更划算，見 03 訊息佇列 的 fan-out 設計
• 複雜事件處理的即時：即時推送需要先做跨資料聚合、過濾、轉換，listener 只能訂 query 結果、表達不了。這類要後端處理後再推，listener 不是合適的傳輸層
• 即時是核心且規模化：當即時同步是產品核心且扇出規模化，整個即時層自建是 Firestore → 自建 relational 裡「realtime / offline 要重建」這項工作量——遷移時這層最容易被低估

判讀的起點是「這份即時是 client 看自己相關的少量資料，還是海量訂閱者看同一份廣播」。前者 listener 是正解，後者從一開始就該用推送架構，而不是把 listener 的扇出推到極限。

下一步路由

• 上層：Firestore overview（realtime / offline 能力與容量特性）
• sibling：distributed counter 高頻寫入（summary 彙總的另一面）
• 授權對齊：Security Rules 授權建模（訂閱範圍與授權範圍一致）
• 推送架構：03 訊息佇列（超高扇出 broadcast 的去處）
• 成本邊界：9.7 成本邊界與 efficiency
• 官方：Firestore pricing、Listen to realtime updates

本文是 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

為什麼用 emulator

Firestore 的 client 直連模型讓「在本地驗證」變得重要：規則寫錯是資安漏洞、查詢設計錯是成本事故，這些都該在進雲端前用真實求值引擎驗過。Emulator Suite 提供與雲端一致的 Firestore 行為與 Security Rules 求值引擎，是規則測試的官方推薦環境。要留意的邊界是——emulator 模擬功能行為，但不模擬計費與部分 production 規模限制（單 document 寫入軟上限、連線天花板）。涉及成本與規模的判讀仍以雲端為準，emulator lab 會在對應處標明。

章節列表

設計原則

Firestore hands-on 章節以「進雲端前先驗」為中心。操作指令只在能產出 artifact 時出現；每篇都要回答 emulator 在哪裡跑、需要哪些 input、怎麼知道操作成功（query output / 測試斷言 / shard 分佈），以及哪些 production 特性（計費、寫入上限）emulator 不負責、要回雲端確認。

引用路徑

• 上游：Firestore overview
• Deep article：Security Rules 授權建模 / distributed counter 高頻寫入
• 發布證據：6.8 release gate（規則測試接進 gate）
• 官方：Emulator Suite、Connect to Firestore emulator

本文是 Firestore Hands-on 操作路線 的基礎 lab。指令以 Firebase CLI 文件 與 Emulator Suite 文件 為準、最後檢查日 2026-06-16。

Firestore local emulator quickstart 的核心責任是建立後續 Security Rules 測試與 distributed counter lab 共用的本地環境。這個 lab 把 Firestore 從抽象服務轉成可觀察的 emulator、規則檔、seed 資料與 query 結果，全程不碰雲端專案。

本文的驗收標準是：你能在本地啟動 Firestore emulator、用 admin SDK 寫入並查詢一組 seed 資料、看到 emulator UI 裡的資料，並知道 cleanup 路徑。

Lab 環境與前置

Lab 在本地資料夾跑，需要 Node.js 與 Firebase CLI。以下命令建立一個可刪除的工作區並裝好工具。

1mkdir -p /tmp/firestore-lab
2cd /tmp/firestore-lab
3
4# Firebase CLI（已裝可跳過）；用 npx 也可避免全域安裝
5npm install -g firebase-tools
6
7# 本 lab 的 Node 依賴
8npm init -y
9npm install firebase-admin

emulator 需要 Java runtime（Firestore emulator 跑在 JVM 上）。java -version 確認存在；缺的話先裝 JDK 再繼續。驗收 artifact 是 /tmp/firestore-lab 工作區。

Emulator 設定

firebase.json 的核心責任是宣告要啟動哪些 emulator 與對應 port。這裡只開 Firestore 與 UI，不需要真實 Firebase 專案——emulator 用一個 demo project id 即可，demo- 前綴讓 CLI 知道這是純本地、不連雲端。

 1cat > firebase.json <<'JSON'
 2{
 3  "emulators": {
 4    "firestore": { "port": 8080 },
 5    "ui": { "enabled": true, "port": 4000 }
 6  },
 7  "firestore": {
 8    "rules": "firestore.rules"
 9  }
10}
11JSON

Baseline 規則

firestore.rules 的核心責任是定義授權。Quickstart 先用一組明確的 owner-scoped 規則（不是 allow read, write: if true，那是 deep article Case 1 的漏洞）。這份規則後續在 Security Rules test lab 會被測試覆蓋。

 1cat > firestore.rules <<'RULES'
 2rules_version = '2';
 3service cloud.firestore {
 4  match /databases/{database}/documents {
 5    match /notes/{noteId} {
 6      allow read: if request.auth != null
 7                  && resource.data.ownerId == request.auth.uid;
 8      allow create: if request.auth != null
 9                    && request.resource.data.ownerId == request.auth.uid;
10      allow update, delete: if request.auth != null
11                            && resource.data.ownerId == request.auth.uid;
12    }
13  }
14}
15RULES

啟動 emulator

啟動 emulator 的核心責任是讓本地有一個可寫可查的 Firestore。用 demo project id 啟動，emulator UI 在 http://localhost:4000 可看到資料。

1firebase emulators:start --only firestore --project demo-firestore-lab

這個指令會 foreground 跑住 emulator。保持它開著，另開一個 terminal 做 seed 與 query。終端輸出會印出 Firestore emulator 的位址（預設 localhost:8080）與 UI 位址。

Seed 資料（admin SDK 繞過規則）

Seed 的核心責任是建立可重跑的測試資料。admin SDK 連到 emulator 時繞過 Security Rules（模擬後端的特權寫入），適合種資料。關鍵是設 FIRESTORE_EMULATOR_HOST 環境變數——有了它，admin SDK 的寫入全部導向 emulator、不需要任何雲端 credential。

 1cat > seed.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5
 6async function main() {
 7  await db.collection('notes').doc('n1').set({
 8    ownerId: 'alice', text: 'Alice first note', createdAt: Date.now(),
 9  });
10  await db.collection('notes').doc('n2').set({
11    ownerId: 'bob', text: 'Bob first note', createdAt: Date.now(),
12  });
13  console.log('seeded 2 notes');
14}
15main().then(() => process.exit(0));
16JS
17
18# 在新 terminal、同 lab 目錄下
19export FIRESTORE_EMULATOR_HOST=localhost:8080
20node seed.js

預期輸出 seeded 2 notes。打開 http://localhost:4000/firestore 應看到 notes collection 下兩筆 document。

Query baseline

Query 的核心責任是確認資料可讀、access pattern 入口可用。admin SDK 同樣繞過規則，這裡驗證的是資料與查詢本身（規則的放行 / 拒絕在下一個 lab 用 client context 驗）。

 1cat > query.js <<'JS'
 2const admin = require('firebase-admin');
 3admin.initializeApp({ projectId: 'demo-firestore-lab' });
 4const db = admin.firestore();
 5
 6async function main() {
 7  const snap = await db.collection('notes')
 8    .where('ownerId', '==', 'alice').get();
 9  console.log(`alice notes: ${snap.size}`);
10  snap.forEach((d) => console.log(d.id, d.data().text));
11}
12main().then(() => process.exit(0));
13JS
14
15export FIRESTORE_EMULATOR_HOST=localhost:8080
16node query.js

預期輸出 alice notes: 1 與 n1 Alice first note。這證明 where('ownerId', '==', ...) 的 access pattern 成立——它也正是 client 端要自帶、好讓 owner-scoped 規則放行的查詢條件。

Artifact 與驗收

Cleanup

Cleanup 的核心責任是讓 lab 可重跑。emulator 的資料在 process 結束時預設不持久化（除非設了 --export-on-exit），所以停掉 emulator 等於清空資料。

1# 停掉 emulator：在 emulator terminal 按 Ctrl-C
2# 移除整個工作區
3rm -rf /tmp/firestore-lab

若想保留 emulator 資料跨 session，啟動時加 --import=./data --export-on-exit=./data；lab 預設不持久化，保持每次乾淨起步。

完成本篇後，下一步進 Security Rules test lab（把上面的規則寫成自動化測試）或 Distributed counter lab。

引用路徑

• 上游：Firestore Hands-on 操作路線
• Deep article：Security Rules 授權建模
• 官方：Install Firebase CLI、Connect to Firestore emulator

本文是 Firestore Hands-on 操作路線 的 lab，實作 Security Rules 授權建模 deep article 的測試方法。前置環境見 Local emulator quickstart。測試 API 以 Rules unit testing 文件 為準、最後檢查日 2026-06-16。

Firestore Security Rules test lab 的核心責任是把授權規則變成可自動驗證的測試。規則是 client 直連模型的整個控制面，改一條就要證明沒開新洞——這個 lab 用 @firebase/rules-unit-testing 在 emulator 上對規則跑斷言，產出可接進 CI 與 release gate 的測試 evidence。

本文的驗收標準是：你能對一組規則寫出「放行 / 越權拒絕 / 未登入拒絕 / 欄位竄改拒絕」四類斷言、用 firebase emulators:exec 一鍵跑完、並看到 assertFails 確實證明該擋的有擋住。

Lab 環境與依賴

沿用 quickstart 的工作區與 firebase.json / firestore.rules。再裝測試依賴。

1cd /tmp/firestore-lab
2npm install --save-dev @firebase/rules-unit-testing firebase jest

驗收前置是 firestore.rules 存在（quickstart 已建立 owner-scoped 規則）與 firebase.json 宣告了 Firestore emulator。

升級規則：加入欄位竄改防護

quickstart 的規則擋了越權讀寫，但還沒擋「owner 改自己 note 時偷改 ownerId 把資料轉走」。先把規則升級到帶欄位白名單，讓測試有更多面向可驗。

 1cat > firestore.rules <<'RULES'
 2rules_version = '2';
 3service cloud.firestore {
 4  match /databases/{database}/documents {
 5
 6    function isSignedIn() { return request.auth != null; }
 7
 8    function ownsExisting() {
 9      return isSignedIn() && resource.data.ownerId == request.auth.uid;
10    }
11
12    function onlyChanges(fields) {
13      return request.resource.data.diff(resource.data).affectedKeys().hasOnly(fields);
14    }
15
16    match /notes/{noteId} {
17      allow read: if ownsExisting();
18      allow create: if isSignedIn()
19                    && request.resource.data.ownerId == request.auth.uid;
20      allow update: if ownsExisting() && onlyChanges(['text', 'updatedAt']);
21      allow delete: if ownsExisting();
22    }
23  }
24}
25RULES

onlyChanges(['text', 'updatedAt']) 是這版的重點：update 只准動 text 與 updatedAt，碰 ownerId 直接拒絕。下面的測試會驗證它。

寫測試：四類斷言

測試的核心責任是覆蓋「該放行的放行、該拒絕的拒絕」。initializeTestEnvironment 載入規則、authenticatedContext 模擬登入身分、assertSucceeds / assertFails 對操作斷言。預先種資料用 withSecurityRulesDisabled 繞過規則。

 1cat > rules.test.js <<'JS'
 2const {
 3  initializeTestEnvironment, assertFails, assertSucceeds,
 4} = require('@firebase/rules-unit-testing');
 5const { doc, getDoc, setDoc, updateDoc } = require('firebase/firestore');
 6const fs = require('fs');
 7
 8let testEnv;
 9
10beforeAll(async () => {
11  testEnv = await initializeTestEnvironment({
12    projectId: 'demo-firestore-lab',
13    firestore: { rules: fs.readFileSync('firestore.rules', 'utf8') },
14  });
15});
16afterAll(async () => { await testEnv.cleanup(); });
17beforeEach(async () => {
18  await testEnv.clearFirestore();
19  await testEnv.withSecurityRulesDisabled(async (ctx) => {
20    await setDoc(doc(ctx.firestore(), 'notes/n1'),
21      { ownerId: 'alice', text: 'hi', updatedAt: 0 });
22  });
23});
24
25// 1. 放行：owner 讀自己的
26test('owner reads own note', async () => {
27  const db = testEnv.authenticatedContext('alice').firestore();
28  await assertSucceeds(getDoc(doc(db, 'notes/n1')));
29});
30
31// 2. 越權拒絕：非 owner 讀別人的
32test('non-owner cannot read', async () => {
33  const db = testEnv.authenticatedContext('bob').firestore();
34  await assertFails(getDoc(doc(db, 'notes/n1')));
35});
36
37// 3. 未登入拒絕
38test('unauthenticated denied', async () => {
39  const db = testEnv.unauthenticatedContext().firestore();
40  await assertFails(getDoc(doc(db, 'notes/n1')));
41});
42
43// 4. 欄位竄改拒絕：owner 偷改 ownerId
44test('owner cannot change ownerId', async () => {
45  const db = testEnv.authenticatedContext('alice').firestore();
46  await assertFails(updateDoc(doc(db, 'notes/n1'), { ownerId: 'bob' }));
47});
48
49// 4b. 正當 update 放行
50test('owner can edit text', async () => {
51  const db = testEnv.authenticatedContext('alice').firestore();
52  await assertSucceeds(updateDoc(doc(db, 'notes/n1'), { text: 'edited', updatedAt: 1 }));
53});
54JS

四類斷言裡 assertFails 比 assertSucceeds 更重要——它證明的是攻擊路徑被擋住，正是滲透測試會打的點。每條規則至少要有「正向放行 + 至少一條拒絕」配對，光測 happy path 證明不了授權安全。

一鍵跑：emulators:exec

跑測試的核心責任是讓它在乾淨 emulator 上自動化執行。firebase emulators:exec 啟動 emulator、跑指定命令、結束後關閉——適合 CI，不需要手動開關 emulator。

1cat > package.json.test <<'JSON'
2{ "scripts": { "test:rules": "jest rules.test.js" } }
3JSON
4# 把 test:rules script 併進既有 package.json 後執行：
5
6firebase emulators:exec --only firestore --project demo-firestore-lab "npx jest rules.test.js"

預期輸出五個測試全 pass：

1PASS  ./rules.test.js
2  owner reads own note (passed)
3  non-owner cannot read (passed)
4  unauthenticated denied (passed)
5  owner cannot change ownerId (passed)
6  owner can edit text (passed)
7
8Test Suites: 1 passed, 1 total
9Tests:       5 passed, 5 total

（Jest 預設 reporter 每行會印一個通過標記、此處以 (passed) 文字呈現，實際終端輸出為工具自身格式。）

故意改壞驗證測試有效

測試的價值在於它會抓到回歸。把規則改回 allow read, write: if true 再跑，應看到「越權拒絕」「未登入拒絕」「欄位竄改拒絕」三個測試 fail——這證明測試確實守在攻擊路徑上，而不是恆綠的假測試。

1# 暫時把規則改成全放行
2printf "rules_version='2';\nservice cloud.firestore{match /databases/{db}/documents{match /{d=**}{allow read,write:if true;}}}" > firestore.rules
3firebase emulators:exec --only firestore --project demo-firestore-lab "npx jest rules.test.js"
4# 預期：3 個 assertFails 測試 fail（該擋的沒擋）
5# 驗證完改回上面的正確規則

Artifact 與驗收

接進 release gate

規則測試的下游責任是成為發布證據。把 firebase emulators:exec ... jest 接進 CI pipeline，規則變更的 PR 必須通過才能 merge——這把「規則改動沒開新洞」從人工推敲變成 gate 條件，對齊 6.8 release gate 的 Gate decision / Checks / Stop condition。授權翻譯的正確性是安全邊界，這個 gate 比一般功能測試更該設為硬性 stop condition。

Cleanup

1# emulators:exec 跑完會自動關 emulator；清依賴與工作區
2rm -rf /tmp/firestore-lab

引用路徑

• 上游：Firestore Hands-on 操作路線
• Deep article：Security Rules 授權建模與可測試化
• 安全驗證：1.5 資料層紅隊
• 發布證據：6.8 release gate
• 官方：Rules unit testing、emulators:exec