修好「Missing or insufficient permissions」：用 Firebase CLI 部署 Firestore 安全規則

一句話：Missing or insufficient permissions 幾乎都是 Firestore 安全規則把讀寫擋掉了。寫好 firestore.rules，用 npx firebase-tools deploy --only firestore:rules 部署上去，就解了。

關鍵字：Firestore、安全規則、Security Rules、Missing or insufficient permissions、Firebase CLI、firebase-tools、firebase login、deploy、firestore.rules、Authorized domains、授權網域

---

問題：雲端連線測試失敗

你的純前端網站已經接上 Firebase（拿到 firebaseConfig 了），但一按「雲端連線測試」就跳紅字：

✗ 連線測試失敗
Missing or insufficient permissions.

還沒拿到 SDK 設定的話，先看 在 Firebase 註冊 Web App 取得 SDK 設定（整個 Firebase 系列從建立專案開始）。

為什麼？因為 Firestore 預設「全部拒絕」

這不是你 code 寫錯，而是 Firestore 的安全規則（Security Rules） 預設就把所有讀寫擋掉——這是 Firebase 刻意的安全預設，避免你的資料庫一開就門戶大開。要讓前端能讀寫，你得部署一份允許特定存取的規則。

規則可以在 Console 網頁裡直接改，但更可重複、可進版控的做法是把規則寫成專案裡的 firestore.rules 檔，用 Firebase CLI 部署。

---

Step 1：安裝 Firebase CLI（firebase-tools）

不用全域安裝，用 npx 直接跑即可。在你的專案目錄執行：

npx firebase-tools --version

第一次會問你是否允許下載執行 npx 套件，選允許即可。

---

Step 2：登入 Firebase

npx firebase-tools login

這會開啟瀏覽器要你授權（跟 Google 登入一樣）。授權成功後瀏覽器會顯示 「Firebase CLI Login Successful」，回終端機就能繼續。

🚨 背景／非互動環境登不了？

如果你是在 AI agent 或背景程序裡跑（非互動模式），login 沒辦法跳出瀏覽器互動。解法是自己另開一個終端機手動跑 npx firebase-tools login 完成授權，登入狀態會共用，再回原本流程繼續 deploy。

---

Step 3：部署 Firestore 規則

確定專案裡有寫好的 firestore.rules（以及指定專案的 .firebaserc）後，只部署規則這一項：

npx firebase-tools deploy --only firestore:rules

--only firestore:rules 表示「只動規則，別碰 Hosting／Functions 等其他東西」，最安全。

---

Step 4：在 Console 確認規則已上線

回到 Firebase Console → Firestore Database → 規則（Rules） 分頁，應該能看到你剛部署的規則內容（rules_version = '2' 開頭）。看到這份就代表規則已生效。

規則裡常見的寫法是「登入的使用者才能讀寫」或「只有特定 admin email 能寫」。apiKey 不是你的防線，這份規則才是真正決定誰能碰你資料的關卡。

---

Step 5：驗證資料真的寫得進去

回網站再按一次「雲端連線測試」，這次應該成功。到 Firestore Database → 資料庫（Data） 也能看到對應的 collection／document 被寫進去了。

---

🚨 部署完規則還是連不上？檢查授權網域

如果規則沒問題、卻還是失敗（尤其是登入相關功能），多半是你的網站網域沒被列進授權網域。到 Authentication → 設定 → 授權網域（Authorized domains） 確認清單裡有你的網域：

• localhost（本機開發用，預設就有）
• <你的專案>.firebaseapp.com、<你的專案>.web.app（Firebase Hosting 預設網域）
• 你自己的網域（例如 GitHub Pages 的 xxx.github.io 或自訂網域）——這個常常忘記加，加上去才放行。

---

重點回顧

• Missing or insufficient permissions = Firestore 安全規則擋住了，不是你 code 壞掉。
• 用 npx firebase-tools 免全域安裝；login 在背景環境跑不動就另開終端機手動登入。
• 部署只動規則：npx firebase-tools deploy --only firestore:rules。
• 在 Console 的 規則 與 資料 分頁雙重確認生效。
• 規則對了還連不上 → 檢查 Authorized domains 有沒有加你的網域（最常被忘記）。
• 真正保護資料的是安全規則，不是把 apiKey 藏起來。

---

下一步：雲端後端搞定了，把網站本身免費上線 → 部署靜態網站／PWA 到 GitHub Pages