建構 Cloud Firestore 安全性規則

Cloud Firestore Security Rules可讓您控管資料庫中文件和集合的存取權。靈活的規則語法可讓您建立符合任何條件的規則，從整個資料庫的所有寫入作業，到特定文件的作業，都能涵蓋在內。

本指南說明安全性規則的基本語法和結構。將這個語法與安全性規則條件結合，即可建立完整的規則集。

如需 AI 輔助，請將下方提示詞複製到 AI 程式設計代理 (例如 Android Studio 內建 Gemini、Antigravity、Claude Code、Codex 和 Cursor)。您可以自訂提示，並與代理反覆調整。如需詳細安裝資訊，請參閱 Firebase 代理技能。 

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me write, validate, and deploy Firebase Security Rules to protect my app's Firestore data.

服務和資料庫宣告

Cloud Firestore Security Rules 一律以以下宣告開頭：

service cloud.firestore {
  // The {database} wildcard allows the rules to reference any database,
  // but these rules are only active on databases where they are explicitly deployed.
  match /databases/{database}/documents {
    // ...
  }
}

service cloud.firestore 宣告會將規則範圍限定在規則，避免 Cloud Firestore Security Rules 與其他產品 (例如 Cloud Storage) 的規則發生衝突。

match /databases/{database}/documents 宣告會指定規則應與專案中的任何規則資料庫相符。雖然專案最多可包含 100 個資料庫，但只有第一個建立的資料庫會設為預設資料庫。

Cloud Firestore Security Rules會分別套用至專案中的每個具名資料庫。也就是說，如果您建立多個資料庫，就必須分別管理及部署各個資料庫的規則。如需部署更新的詳細操作說明，請參閱「部署更新」。

基本讀取/寫入規則

基本規則包含指定文件路徑的 match 陳述式，以及詳細說明何時允許讀取指定資料的 allow 運算式：

service cloud.firestore {
  match /databases/{database}/documents {

    // Match any document in the 'cities' collection
    match /cities/{city} {
      allow read: if <condition>;
      allow write: if <condition>;
    }
  }
}

所有比對陳述式都應指向文件，而非集合。比對陳述式可以指向特定文件 (如 match /cities/SF)，或使用萬用字元指向指定路徑中的任何文件 (如 match /cities/{city})。

在上述範例中，比對陳述式使用 {city} 萬用字元語法。這表示規則適用於 cities 集合中的任何文件，例如 /cities/SF 或 /cities/NYC。評估比對陳述式中的 allow 運算式時，city 變數會解析為城市文件名稱，例如 SF 或 NYC。

精細作業

在某些情況下，建議您將 read 和 write 細分為更精細的操作。舉例來說，應用程式可能想對文件建立和文件刪除強制執行不同條件。或者，您可能想允許讀取單一文件，但拒絕大型查詢。

read 規則可拆分為 get 和 list，而 write 規則可拆分為 create、update 和 delete：

service cloud.firestore {
  match /databases/{database}/documents {
    // A read rule can be divided into get and list rules

    match /cities/{city} {
      // Applies to single document read requests
      allow get: if <condition>;

      // Applies to queries and collection read requests
      allow list: if <condition>;
    }
    // A write rule can be divided into create, update, and delete rules
    match /cities/{city} {
      // Applies to writes to nonexistent documents
      allow create: if <condition>;

      // Applies to writes to existing documents
      allow update: if <condition>;

      // Applies to delete operations
      allow delete: if <condition>;
    }
  }
}

階層式資料

Rules 中的資料會整理成文件集合，每份文件都可透過子集合擴充階層。請務必瞭解安全性規則與階層式資料的互動方式。

假設 cities 集合中的每份文件都包含 landmarks 子集合。安全性規則只會套用至相符的路徑，因此在 cities 集合上定義的存取控管機制，不會套用至 landmarks 子集合。請改為編寫明確規則，控管子集合的存取權：

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      allow read, write: if <condition>;

        // Explicitly define rules for the 'landmarks' subcollection
        match /landmarks/{landmark} {
          allow read, write: if <condition>;
        }
    }
  }
}

巢狀結構 match 陳述式中，內部 match 陳述式的路徑一律相對於外部 match 陳述式的路徑。因此，下列規則集等同：

service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city} {
      match /landmarks/{landmark} {
        allow read, write: if <condition>;
      }
    }
  }
}
 
service cloud.firestore {
  match /databases/{database}/documents {
    match /cities/{city}/landmarks/{landmark} {
      allow read, write: if <condition>;
    }
  }
}

遞迴萬用字元

如要將規則套用至任意深度的階層，請使用遞迴萬用字元語法 {name=**}。例如：

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the cities collection as well as any document
    // in a subcollection.
    match /cities/{document=**} {
      allow read, write: if <condition>;
    }
  }
}

使用遞迴萬用字元語法時，萬用字元變數會包含整個相符的路徑區段，即使文件位於深度巢狀子集合中也一樣。舉例來說，上述規則會比對位於 /cities/SF/landmarks/coit_tower 的文件，而 document 變數的值會是 SF/landmarks/coit_tower。

不過，請注意，遞迴萬用字元的行為取決於規則版本。

版本 1

安全性規則預設使用第 1 版。在第 1 版中，遞迴萬用字元會比對一或多個路徑項目。這類萬用字元不符合空白路徑，因此 match /cities/{city}/{document=**} 會比對子集合中的文件，但不會比對 cities 集合中的文件，而 match /cities/{document=**} 則會比對 cities 集合和子集合中的文件。

遞迴萬用字元必須位於比對陳述式的結尾。

第 2 版

在第 2 版安全性規則中，遞迴萬用字元會比對零或多個路徑項目。match/cities/{city}/{document=**} 會比對任何子集合中的文件，以及 cities 集合中的文件。

您必須在安全性規則頂端加入 rules_version = '2';，才能選擇加入第 2 版：

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the cities collection as well as any document
   // in a subcollection.
   match /cities/{city}/{document=**} {
     allow read, write: if <condition>;
   }
 }
}

每個比對陳述式最多只能有一個遞迴萬用字元，但在第 2 版中，您可以將這個萬用字元放在比對陳述式中的任何位置。例如：

rules_version = '2';
service cloud.firestore {
 match /databases/{database}/documents {
   // Matches any document in the songs collection group
   match /{path=**}/songs/{song} {
     allow read, write: if <condition>;
   }
 }
}

如果您使用集合群組查詢，則必須使用第 2 版，請參閱「保護集合群組查詢」。

重疊的相符陳述式

一份文件可能符合多個 match 陳述式。如果有多個 allow 運算式與要求相符，只要任一條件為 true，系統就會允許存取：

service cloud.firestore {
  match /databases/{database}/documents {
    // Matches any document in the 'cities' collection.
    match /cities/{city} {
      allow read, write: if false;
    }

    // Matches any document in the 'cities' collection or subcollections.
    match /cities/{document=**} {
      allow read, write: if true;
    }
  }
}

在上述範例中，系統會允許對 cities 集合的所有讀取和寫入作業，因為第二個規則一律為 true，即使第一個規則一律為 false。

安全性規則限制

使用安全性規則時，請注意下列限制：

限制 說明
每項要求的 exists()、get() 和 getAfter() 呼叫數量上限
  • 單一文件要求和查詢要求的上限為 10 項。

  • 多文件讀取作業、交易和批次寫入作業的上限為 20 項。上述限制 (10 項呼叫) 同樣適用於各項作業。

    舉例來說，假設您建立的批次寫入要求含有 3 項寫入作業，而您的安全性規則會使用 2 項文件存取呼叫來驗證各項寫入作業。此時，各項寫入作業會使用 2 項存取呼叫 (上限為 10 項)，批次寫入要求則會使用 6 項存取呼叫 (上限為 20 項)。

超過任一項限制都會引發權限遭拒的錯誤。

系統可能會快取部分的文件存取呼叫，已快取的呼叫不會計入限制中。
巢狀 match 陳述式深度上限 10
一組巢狀 match 陳述式中允許的路徑長度上限 (以路徑區段為單位) 100
一組巢狀 match 陳述式中允許的路徑擷取變數數量上限 20
函式呼叫深度上限 20
函式引數數量上限 7
每個函式的 let 變數繫結上限 10
遞迴或循環函式呼叫的數量上限 0 (不允許)
每個要求中經評估的運算式數量上限 1,000 個
規則集的大小上限 規則集必須遵守兩項大小限制：
  • 從 Firebase 控制台或使用 firebase deploy 透過 CLI 發布的規則集文字來源大小上限為 256 KB。
  • Firebase 處理來源並在後端啟用時，產生的編譯規則集大小上限為 250 KB。

後續步驟