更新记录

1.0.0（2026-03-30）

Firestore UTS 插件，支持 iOS 与 Android，提供 set / setMerge / update / add / get / delete 及 onSnapshot 实时监听（listen / unlisten）。

平台兼容性

firestore-database

Firestore UTS 插件，支持 iOS 与 Android，提供 set / setMerge / update / add / get / delete 及 onSnapshot 实时监听（listen / unlisten）。

使用前准备

客户端 vs 服务端配置（重要）

uni-app 客户端：必须用 Firebase 客户端配置，不能使用 service account：
- Android：在项目根目录放 google-services.json（从 Firebase 控制台 → 项目设置 → 您的应用 → 下载「Google 服务」配置文件）。
- iOS：在原生工程放 GoogleService-Info.plist（同上，选 iOS 应用下载）。
若 Node 里用了 getFirestore('device')，说明你用的是命名数据库，数据库 ID 为 'device'。客户端必须连同一数据库，创建插件时传 databaseId: 'device'：
```
this.globalData.firestore = new FirestorePluginImpl({ databaseId: 'device' })
```
不传或传空则使用默认库 (default)。

Android

在项目根目录配置 google-services.json（从 Firebase 控制台「项目设置 → 您的应用」下载，不是 service account 的 json）。
确保主工程已应用 Google Services 插件并完成 Firebase 默认初始化（云打包或自定义基座通常会自动处理）。

iOS（真实 Firestore 已内置）

CocoaPods：插件在 app-ios/config.json 中声明 FirebaseCore 与 Firebase/Firestore，云打包或本地打包时会自动集成。
GoogleService-Info.plist：从 Firebase 控制台下载 iOS 应用的配置文件，放到工程的 nativeResources/ios/ 目录（或按 manifest 的 sdkConfigs.statics.google.config_ios 配置的路径），确保打包时能打进 App。
初始化：插件在首次调用 Firestore 时会自动执行 FirebaseApp.configure()，无需在 AppDelegate 中手动写代码。
若仍提示「Firebase/Firestore 未配置」，请确认 plist 已正确放入并重新打自定义基座后再运行。

iOS 本地打包失败（log 末尾大量 gRPC/abseil 的 C++17 警告）

插件依赖 Firebase → gRPC-Core → abseil。本地真机运行/本地打包时，若本机 Xcode 版本过新（如 Xcode 26 / iOS 26 SDK），编译 abseil/gRPC 可能出现：

warning: use of the 'fallthrough' attribute is a C++17 extension [-Wc++17-attribute-extensions]
若工程将警告视为错误，会导致编译失败，且 log 可能被截断、看不到明确 error 行。

建议：优先使用 云打包（安心打包）；若必须本地打包，请使用与云端打包环境一致的 Xcode 16.x（参见 iOS 平台云端打包环境），避免用 Xcode 26 等过新版本。

使用方式

在 App.vue 中（与 host-ip-plugin 类似）：

// #ifdef APP-PLUS
import { FirestorePluginImpl } from '@/uni_modules/firestore-database'
// #endif

export default {
  onLaunch() {
    // #ifdef APP-PLUS
    this.globalData.firestore = new FirestorePluginImpl()
    // #endif
  },
  globalData: {
    firestore: null
  }
}

在业务中通过 getApp().globalData.firestore 调用：

const firestore = getApp().globalData.firestore
if (firestore) {
  firestore.set('users', 'user1', { name: 'Tom', age: 18 }, (res) => {
    if (res.success) console.log('写入成功')
    else console.log(res.errMsg)
  })
  firestore.get('users', 'user1', (res) => {
    if (res.success) console.log(res.data)
  })
  firestore.delete('users', 'user1', (res) => {
    if (res.success) console.log('删除成功')
  })
  // 实时监听（onSnapshot）
  const listenerId = firestore.listen('users', 'user1', (res) => {
    if (res.success) console.log('文档更新', res.data)
    else console.warn(res.errMsg)
  })
  // 取消监听
  firestore.unlisten(listenerId)
}

API

set(collection, doc, data, callback)：写入或覆盖文档（增 / 改都用它）
setMerge(collection, doc, data, callback)：写入但不覆盖未提供字段（merge）
update(collection, doc, data, callback)：仅更新指定字段（不覆盖整份文档）；文档不存在会失败（与官方一致）
add(collection, data, callback)：新增文档（自动生成 docId），成功时 res.data = { id: string }
get(collection, doc, callback)：读取文档，成功时 res.data 为文档数据
delete(collection, doc, callback)：删除文档
listen(collection, doc, callback)：监听文档变化（onSnapshot），返回 listenerId
unlisten(listenerId)：取消监听

FieldValue（可选）

在 setMerge/update 的 data 中，你可以用以下对象字面量表示 Firestore 的 FieldValue 操作（普通写法完全不受影响）：

// 删除字段
{ someField: { __op: 'delete' } }

// 自增/自减
{ counter: { __op: 'increment', by: 1 } }
{ counter: { __op: 'increment', by: -2 } }

// 数组并集/移除
{ tags: { __op: 'arrayUnion', values: ['a', 'b'] } }
{ tags: { __op: 'arrayRemove', values: ['a'] } }

// 服务器时间戳
{ updatedAt: { __op: 'serverTimestamp' } }

回调 res 包含：success、data（get/listen 成功时有值）、errMsg。