Firebase Firestore 数据库技能（状态：Production Ready，最后更新：2026-01-25，依赖：无，为独立技能；最新版本：firebase@12.8.0、firebase-admin@13.6.0）。
一、用途 本技能用于基于 Firestore NoSQL 数据库进行开发，提供实时同步、离线支持与可扩展的文档存储能力。适用于创建集合、查询文档等场景。
二、快速开始
- 安装 Firebase SDK：客户端 SDK（Web/移动端）执行 npm install firebase；管理端 SDK（服务端/后端）执行 npm install firebase-admin。
- 初始化 Firebase（客户端）：在 src/lib/firebase.ts 中从 firebase/app 导入 initializeApp，从 firebase/firestore 导入 getFirestore，使用包含 apiKey、authDomain、projectId、storageBucket、messagingSenderId、appId 的 firebaseConfig 初始化应用并导出 db。
- 初始化 Firebase Admin（服务端）：在 src/lib/firebase-admin.ts 中从 firebase-admin/app 导入 initializeApp、cert、getApps，从 firebase-admin/firestore 导入 getFirestore；仅在 getApps().length 为空时初始化，使用 cert 传入 projectId、clientEmail 与 privateKey（需将转义换行替换为真实换行），并导出 adminDb。 关键注意：绝不在客户端代码中暴露 FIREBASE_PRIVATE_KEY；服务端操作使用 Admin SDK（绕过安全规则）；已认证用户操作使用客户端 SDK。
三、主要能力
- 文档 CRUD：客户端 SDK（模块化 v9+）支持 addDoc（自动生成 ID）、setDoc（指定 ID）、getDoc（读取单个文档）、getDocs 配合 query（集合查询）、updateDoc（合并字段更新）、setDoc 配合 merge（不存在则创建）、deleteDoc（删除）。Admin SDK 提供对应的 collection().add()、doc().set()、doc().get()、where/orderBy/limit 查询、update()、delete() 等操作。
- 实时监听（客户端 SDK）：使用 onSnapshot 监听单个文档或带查询的集合，支持错误回调；必须在结束时取消订阅（如 React useEffect 清理函数），以避免内存泄漏；监听器占用并发连接上限，每个监听器是一个 WebSocket 连接。
- 查询模式：支持复合查询（多个 where 子句需复合索引）、范围查询（仅一个字段可使用不等式）、array-contains、array-contains-any（最多 30 个值）、in（最多 30 个值）、not-in（最多 10 个值）；支持基于游标的分页（startAfter 配合 lastVisible）；支持集合组查询（collectionGroup，跨所有同名子集合查询，必须创建索引）。
- 批量操作与事务：writeBatch 支持最多 500 个操作并原子提交；runTransaction 支持先读后写，事务可自动重试（最多 5 次），事务内不应执行副作用，所有读取必须在写入之前。
- 安全规则：提供 firestore.rules 结构示例，包含辅助函数（isAuthenticated、isOwner、isValidUser）、users 集合、posts 集合及其 comments 子集合、admin 集合的读写规则；部署命令为 firebase deploy --only firestore:rules 或 firebase deploy --only firestore。
- 索引：通过 firestore.indexes.json 定义复合索引（含 collectionGroup、queryScope、fields），部署命令为 firebase deploy --only firestore:indexes。Firestore 自动创建单字段索引；复合索引需手动创建或通过错误链接创建；集合组查询始终需要索引。
- 离线持久化：Web 端可通过 initializeFirestore 配合 persistentLocalCache 与 persistentMultipleTabManager 启用多标签页离线持久化，或使用 enableIndexedDbPersistence 启用单标签页持久化（需处理 failed-precondition 与 unimplemented 错误）；可通过 doc.metadata.fromCache 与 hasPendingWrites 判断数据来源与待同步状态。
- 数据建模最佳实践：为读性能进行反规范化（在文档中直接存储作者信息）；子集合适合父子关系，根集合适合跨领域查询；高写入场景可使用计数器模式（低流量用 increment，高流量用分布式计数器分片）。
四、错误处理 常见错误包括：permission-denied（安全规则阻止访问，检查规则并确保用户已认证）、not-found（文档不存在，访问前用 exists() 检查）、already-exists（ID 已存在，使用 setDoc 配合 merge 或生成新 ID）、resource-exhausted（配额超限，升级计划或优化查询）、failed-precondition（缺少索引，通过错误链接创建复合索引）、unavailable（服务暂时不可用，实现带退避的重试）、invalid-argument（无效查询组合）、deadline-exceeded（操作超时，减少数据量或分页）。 查询约束：不能对不同字段使用多个不等式过滤；orderBy 字段必须与不等式字段一致（需先 orderBy 不等式字段）。
五、已知问题预防 本技能可预防 10 个已记录的 Firestore 错误，包括 permission-denied（先在 Firebase 控制台模拟器中测试规则）、failed-precondition 索引缺失（点击错误链接创建索引或在 firestore.indexes.json 中定义）、无效查询组合（多个不等式）等。
六、适用场景与限制 适用于需要实时同步、离线支持与可扩展文档存储的 Web/移动端与服务端应用开发。限制方面：复合索引需手动创建；集合组查询必须建索引；不等式查询与 orderBy 存在约束；批量写入上限 500 个操作；array-contains-any 与 in 最多 30 个值，not-in 最多 10 个值；监听器占用并发连接上限。