開始使用 Cloud Firestore 安全性規則

有了 Cloud Firestore Security Rules，您就能專心打造優質的使用者體驗，不必管理基礎架構，也不必編寫伺服器端驗證和授權程式碼。

安全性規則提供存取控管和資料驗證機制，格式簡單卻能清楚表達。如要建構以使用者和角色為基礎的存取系統，確保使用者資料安全無虞，您需要搭配使用 Firebase Authentication 和 Cloud Firestore Security Rules。

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.

安全性規則第 2 版

自 2019 年 5 月起，Cloud Firestore 安全性規則第 2 版已推出。第 2 版規則會變更遞迴萬用字元 {name=**} 的行為。如要使用集合群組查詢，則必須使用第 2 版。如要選擇加入第 2 版，請務必將 rules_version = '2'; 設為安全性規則的第一行：

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

編寫規則

您將編寫及管理 Cloud Firestore Security Rules，並根據專案中預設資料庫和每個額外資料庫建立的資料模型，量身打造這些規則。

所有 Cloud Firestore Security Rules 都包含 match 陳述式 (用於識別資料庫中的文件) 和 allow 運算式 (用於控管這些文件的存取權)：

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

系統會先根據安全性規則評估 Cloud Firestore 行動/網頁用戶端程式庫的每項資料庫要求，再讀取或寫入任何資料。如果規則拒絕存取任何指定的文件路徑，整個要求就會失敗。

以下是基本規則集的一些範例。雖然這些規則有效，但不建議用於正式版應用程式：

// Allow read/write access on all documents to any user signed in to the application
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if request.auth != null;
    }
  }
}

// Deny read/write access to all users under any conditions
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if false;
    }
  }
}

// Allow read/write access to all users under any conditions
// Warning: **NEVER** use this rule set in production; it allows
// anyone to overwrite your entire database.
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read, write: if true;
    }
  }
}

上述範例中使用的 {document=**} 路徑會比對整個資料庫中的任何文件。請繼續參閱建構安全性規則指南，瞭解如何比對特定資料路徑及處理階層式資料。

測試規則

Cloud Firestore 提供規則模擬器，可用於測試規則集。您可以在 Google Cloud 控制台和 Firebase 控制台存取模擬器。

規則模擬器可讓您模擬經過驗證和未經驗證的讀取、寫入和刪除作業。模擬已驗證的要求時，您可以建構及預覽來自不同供應商的驗證權杖。模擬要求會針對編輯器中的規則集執行，而非已部署的規則集。

在 Google Cloud 控制台測試規則

Google Cloud 控制台中的規則模擬器，適用於原生模式的 Firestore Standard 和 Enterprise 版。

所需權限

如要在 Google Cloud 控制台測試安全性規則，您需要下列 IAM 權限：

• firebaserules.rulesets.test

如要在 Google Cloud 控制台中模擬資料庫要求，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。
2. 按一下要測試的資料庫 ID。
3. 按一下導覽選單中的「Security」(安全性)。
4. 按一下「模擬工具」分頁標籤。
5. 在「Simulation type」(模擬類型) 下拉式選單中，選取作業類型：get、create、update 或 delete。
6. 在「Location」(位置) 欄位中，輸入要測試的文件路徑 (例如 users/user_123)。
7. (選用) 針對 create 和 update 要求，按一下「Build document」(建構文件)，設定模擬文件酬載。
8. (選用) 如要模擬已驗證的要求，請開啟「Authentication」(驗證)，選取驗證供應商 (例如 google.com 或「Anonymous」(匿名))，然後設定權杖酬載欄位。
9. 按一下「執行」。

評估面板會顯示要求是否允許或拒絕、每項評估條件的詳細報表項目，以及程式碼編輯器中的行層級醒目顯示。

在 Firebase 控制台測試規則

如要在 Firebase 控制台中測試規則，請依序前往「Databases & Storage」> 「Firestore」> 「Rules」分頁。按一下「Rules Playground」(規則測試區) 開啟模擬器設定，選取模擬選項，然後按一下「Run」(執行)。

部署規則

您必須先部署安全性規則，才能開始透過行動應用程式使用 Cloud Firestore。您可以在 Firebase 控制台、Google Cloud 控制台，使用 Firebase CLI 或 Cloud Firestore 管理 REST API 部署規則。

Cloud Firestore Security Rules 的更新最多可能需要一分鐘，才會影響新的查詢和監聽器。不過，變更最多可能需要 10 分鐘才會全面生效，並影響所有活躍的事件監聽器。

使用 Firebase 控制台

如要設定及部署第一組規則，請在 Firebase 控制台中，前往專案預設資料庫的「資料庫和儲存空間」>「Firestore」>「規則」分頁。

如果您為專案建立多個資料庫，可以為每個資料庫部署 Cloud Firestore Security Rules。在 Firebase 控制台中，使用資料庫選取器，在預設資料庫和任何其他資料庫之間切換。

在線上編輯器中編寫規則，然後按一下「Publish」(發布)。

使用 Google Cloud 控制台

您可以直接在 Google Cloud 控制台中管理及部署 Cloud Firestore Security Rules。Firestore 原生模式的標準版和 Enterprise 版都提供規則編輯器。

所需權限

如要在 Google Cloud 控制台中管理及部署安全性規則，您需要下列 IAM 權限：

• firebaserules.releases.create
• firebaserules.releases.delete
• firebaserules.releases.update
• firebaserules.rulesets.create
• firebaserules.rulesets.delete
• firebaserules.rulesets.list
• firebaserules.rulesets.test (必須具備這項權限，才能使用規則模擬工具)

如要在 Google Cloud 控制台部署規則，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Databases」(資料庫) 頁面。
2. 按一下要管理的資料庫 ID。
3. 按一下導覽選單中的「Security」(安全性)。
4. 按一下「Firestore 規則」分頁標籤。
5. 在規則編輯器中查看規則。如要編輯，請按一下「New ruleset」(新增規則集) 或「Clone ruleset」(複製規則集)，然後修改規則。
6. 點按「發布」，部署變更。

您也可以在時間軸中查看先前的規則集，並複製或還原這些規則集。

使用 Firebase CLI

您也可以使用 Firebase CLI 部署規則。使用 CLI 可讓您透過應用程式程式碼控管規則版本，並在現有部署程序中部署規則。

// Set up Firestore in your project directory, creates a .rules file
firebase init firestore

// Edit the generated .rules file to your desired security rules
// ...

// Deploy rules for all configured databases
firebase deploy --only firestore

強化 Cloud Storage 的安全性

您的應用程式將受益於 Cloud Firestore 的強大資料庫功能，以及 Cloud Storage 的檔案儲存和管理功能。這些產品搭配使用時，還能強化應用程式安全性，因為 Cloud Firestore 可擷取 Firebase 安全性規則可用的授權需求，並套用至這兩項產品。詳情請參閱 Cloud Storage 指南。

後續步驟

• 瞭解如何建構安全性規則。
• 編寫自訂安全性規則條件。
• 請參閱安全性規則參考資料。