在 Vue 3 项目中用 VueUse useFirestore 实现响应式 Firestore 数据同步

在 Vue 3 项目中用 VueUse useFirestore 实现响应式 Firestore 数据同步【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本指南围绕 VueUse 生态中的useFirestore组合式函数讲解如何在 Vue 3 / Nuxt 3 应用中把 Cloud Firestore 的文档与查询结果变成响应式状态让本地数据始终与远端数据库保持同步。读完本文你将掌握useFirestore的完整用法、响应式查询与条件延迟加载模式、errorHandler与autoDispose选项的实战含义以及通过createGlobalState跨组件共享订阅而不重复计费读数的进阶技巧。本文以仓库 .agents/skills/vueuse-functions/references/useFirestore.md 为骨架撰写并结合本仓库 vueuse-functions 技能定义 与依赖目录如 pnpm-workspace.yaml中的版本信息进行佐证。useFirestore 是什么useFirestore是 VueUsevueuse/firebase子包提供的Reactive Firestore binding。它的核心价值在于把订阅远端数据这件本需要手写onSnapshot监听、手动清理监听器、手动更新响应式状态的繁琐工作压缩成一次函数调用。它专门解决始终让本地数据与远端数据库保持同步这一需求——当 Firestore 服务端数据发生变化时返回的Ref会自动更新驱动组件视图重新渲染。在本仓库的技能体系中useFirestore与 useAuth、useRTDB 同属Firebase类别调用规则为EXTERNAL即仅当用户已经安装了所需的 Firebase 外部依赖时才使用否则应重新评估并在确实需要时才建议安装。这一点对实际工程很有参考意义——引入useFirestore意味着同时引入firebase核心 SDK 与vueuse/firebase需要确认项目确实有 Firestore 数据同步诉求。环境准备与依赖useFirestore运行在 Vue 3或以上/ Nuxt 3或以上项目中。使用时需要两个层面的依赖Firebase 官方 SDKfirebase/app用于初始化应用firebase/firestore提供collection、doc、query、getFirestore、orderBy、limit等 Firestore 构建器。VueUse Firebase 桥接包从vueuse/firebase/useFirestore导入useFirestore本身。本仓库使用 pnpm workspace 的 catalog 机制统一管理 VueUse 版本pnpm-workspace.yaml 中约定vueuse/core与vueuse/shared均为^14.4.0多个应用如 apps/stage-pocket/package.json、apps/stage-web/package.json、apps/stage-tamagotchi/package.json都通过vueuse/core: catalog:引用该版本。vueuse/firebase与vueuse/core同属 VueUse 主版本线建议保持版本一致。基础用法集合、文档与查询useFirestore的第一参数接收三种 Firestore 引用对象之一集合引用CollectionReference、文档引用DocumentReference或查询引用Query。先看最基础的用法import { useFirestore } from vueuse/firebase/useFirestore import { initializeApp } from firebase/app import { collection, doc, getFirestore, limit, orderBy, query } from firebase/firestore import { computed, shallowRef } from vue const app initializeApp({ projectId: MY PROJECT ID }) const db getFirestore(app) // 订阅整个集合等价于全量查询 const todos useFirestore(collection(db, todos)) // 或订阅单个文档 const user useFirestore(doc(db, users, my-user-id))useFirestore(collection(db, todos))监听todos集合返回RefT[]数组中的每个元素都带有自动附加的id只读属性。useFirestore(doc(db, users, my-user-id))监听users/my-user-id单文档返回RefT | null。注意initializeApp时只需projectId即可在本地验证初始化逻辑实际运行需要完整的 Firebase 配置apiKey、authDomain等。初始化一次后通过getFirestore(app)获得数据库实例供全局复用。响应式查询用 ref 驱动查询条件useFirestore的第一个参数类型是MaybeRef...意味着它既可以接收静态的引用/查询对象也可以接收 ref 或 computed 动态值。当查询条件本身是响应式的时候条件变化会触发重新订阅返回的数据也随之更新。// 查询条数可响应式变化 const postsLimit shallowRef(10) const postsQuery computed(() query(collection(db, posts), orderBy(createdAt, desc), limit(postsLimit.value)), ) const posts useFirestore(postsQuery)这段代码实现了最近postsLimit条按时间倒序的文章这一查询。当postsLimit.value从 10 改成 20 时computed重新求值产生新的QueryuseFirestore自动取消旧监听并订阅新查询。这里使用shallowRef而非ref避免对数字这类原始值产生不必要的深层代理开销也是 VueUse 官方示例的推荐写法。同理doc也可以包在computed里做动态文档订阅。条件门控查询就绪后再执行一个非常实用的模式是用布尔值门控查询当门控值为 falsy 时订阅不建立useFirestore直接返回初始值当门控值变为 truthy 时才开始真正的数据监听。典型场景是用户尚未登录 / 尚未拿到 ID 时不发请求// 当 userId 为空字符串时查询不会真正执行 const userId shallowRef() const userQuery computed(() userId.value doc(db, users, userId.value)) const userData useFirestore(userQuery, null)这里userQuery的求值结果是falsy或DocumentReference。useFirestore内部对 falsy 引用不会建立订阅此时userData保持传入的初始值null一旦userId.value被赋值为真实 IDcomputed 产生合法文档引用订阅随即建立数据自动填充。这一设计让依赖前置数据的查询无需手工写 if/else代码意图一目了然。Falsy类型在类型声明中被定义为false | 0 | | null | undefined也就是说任何 falsy 值包括数字 0都可作为门控信号。返回值与文档 id 注入useFirestore的返回值取决于传入的引用类型规则如下Document Reference文档引用返回RefT | null即单个文档对象文档不存在时为null。Query查询含集合引用返回RefT[]即文档对象数组。文档id会自动作为只读属性注入到每一个返回的文档对象上。这意味着你无需在数据里冗余保存id字段直接用todo.id即可拿到 Firestore 文档主键——配合v-for的:key、编辑/删除操作都非常方便。类型签名中同时给出了无初始值时的宽松版本RefT | undefined、RefT[] | undefined。因此期望加载完成前为undefined文档不存在为null可省略initialValue期望加载完成前为空数组避免模板里对undefined做防御传[]作为第二参数期望加载完成前为null传null。Options 选项详解useFirestore第三参数接受UseFirestoreOptions配置对象包含两个可选项Option类型默认值说明errorHandler(err: Error) voidconsole.error自定义错误处理回调订阅/监听出错时被调用autoDisposeboolean \| numbertrue作用域销毁如组件卸载时自动取消订阅传数字时表示延迟多少毫秒后再取消订阅errorHandler自定义错误处理默认情况下监听错误直接打到console.error。生产环境往往需要更精细的处理例如弹出通知或上报监控const todos useFirestore(collection(db, todos), [], { errorHandler: (err) { console.error(Firestore error:, err) // 例如显示通知、上报错误监控 }, })注意错误处理回调不会吞掉订阅本身——它只是接管出错时做什么底层监听关系仍由useFirestore管理。autoDispose自动取消订阅与延迟销毁默认autoDispose: true组件卸载或当前 effect scope 被 dispose 时自动取消 Firestore 订阅避免内存泄漏与多余的监听开销。传入数字毫秒则可实现延迟销毁例如autoDispose: 60000表示组件卸载后 60 秒内若再次创建订阅如快速路由跳回可以直接复用既有监听而不会中断兼顾性能与资源释放。跨实例共享订阅Firestore 按文档读取量计费重复监听同一数据源会造成不必要的资源消耗。useFirestore提供两种共享订阅的途径。方式一autoDispose: false将autoDispose设为false订阅在组件卸载后不被销毁其他实例再次以相同引用调用时直接复用import { useFirestore } from vueuse/firebase/useFirestore import { collection } from firebase/firestore const todos useFirestore(collection(db, todos), undefined, { autoDispose: false })官方文档特别强调重新获取一个未销毁的 db 引用不会产生额外的 Firestore 读取。也就是说多个组件共享同一个autoDispose: false的订阅计费上只算一次读数。代价是监听长期驻留适合低频变化但高频访问的数据也可配合数字型autoDispose做延迟复用折中。方式二createGlobalState 全局状态更符合 Vue 组合式函数风格的做法是用 VueUse 核心包的createGlobalState把订阅封装为全局单例。它把状态保存在全局作用域跨 Vue 实例复用且不会因组件卸载而销毁// store.ts import { createGlobalState } from vueuse/core import { useFirestore } from vueuse/firebase/useFirestore export const useTodos createGlobalState( () useFirestore(collection(db, todos)), )!-- app.vue -- script setup langts import { useTodos } from ./store const todos useTodos() /scriptcreateGlobalState的本质是惰性初始化 单例缓存第一次调用useTodos()时执行工厂函数建立 Firestore 订阅之后任意组件再调用都返回同一份状态。对比可见autoDispose: false直接作用于单个useFirestore调用createGlobalState则是把整个订阅逻辑提升为全局单例二者可组合使用也可与 createGlobalState 参考文档 中提到的useStorage持久化方案叠加实现全局 持久化 实时同步的完整数据层。类型声明深入useFirestore通过函数重载为不同引用类型提供精确的返回类型推导export interface UseFirestoreOptions { errorHandler?: (err: Error) void autoDispose?: boolean | number } export type FirebaseDocRefT QueryT | DocumentReferenceT type Falsy false | 0 | | null | undefined export declare function useFirestoreT extends DocumentData( maybeDocRef: MaybeRefDocumentReferenceT | Falsy, initialValue: T, options?: UseFirestoreOptions, ): RefT | null export declare function useFirestoreT extends DocumentData( maybeDocRef: MaybeRefQueryT | Falsy, initialValue: T[], options?: UseFirestoreOptions, ): RefT[] export declare function useFirestoreT extends DocumentData( maybeDocRef: MaybeRefDocumentReferenceT | Falsy, initialValue?: T | undefined | null, options?: UseFirestoreOptions, ): RefT | undefined | null export declare function useFirestoreT extends DocumentData( maybeDocRef: MaybeRefQueryT | Falsy, initialValue?: T[], options?: UseFirestoreOptions, ): RefT[] | undefined几个值得注意的推导细节泛型T extends DocumentData约束数据为 Firestore 文档数据结构字段值为可序列化的 Firestore 支持类型。MaybeRef...即值或 ref 或 getter这正是前文响应式查询与条件门控能工作的类型基础。重载按是否提供初始值区分返回类型提供T/T[]时返回确定的RefT | null/RefT[]省略时则为带undefined的宽松类型。这提示我们如果你希望模板里少写空值防御显式传入初始值即可获得更精确的类型。与仓库技能体系的配合在本仓库的 vueuse-functions 技能SKILL.md中useFirestore与useAuth、useRTDB一起构成 Firebase 数据层的组合式函数方案useAuth负责认证状态useFirestore负责文档/集合级实时同步useRTDB 则覆盖 Realtime Database 的场景三者调用规则均为 EXTERNAL——即只有项目已具备 Firebase 依赖时才引入。这种先评估依赖、后使用函数的纪律与本仓库以 pnpm catalog 统一锁定vueuse/*版本pnpm-workspace.yaml 中^14.4.0的工程化实践是一致的。小结useFirestore把 Firestore 的实时订阅封装为一行响应式绑定集合与查询返回RefT[]、文档返回RefT | nullid自动注入MaybeRef参数让查询条件、门控逻辑天然响应式errorHandler接管错误处理autoDispose以布尔值或毫秒数控制订阅生命周期配合autoDispose: false或createGlobalState可实现跨组件、跨实例的单次读取共享。对于需要在 Vue 3 应用中快速落地本地与云端实时一致数据层的团队这是开箱即用的方案。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考