AngularFire 安装与项目初始化指南：从 `ng add @angular/fire` 到 Firestore 数据流绑定

后端【免费下载链接】angularfireAngular Firebase ❤️项目地址https://gitcode.com/gh_mirrors/an/angularfire点击查看免费下载导读本文基于 AngularFire 官方 Quickstart 文档docs/install-and-setup.md编写完整讲解在全新 Angular 项目中接入 AngularFire 的六个步骤创建项目、运行ng add angular/fire、注入Firestore、把集合绑定为响应式列表、本地联调、部署上线。你将掌握ng add背后的 schematics 究竟改动了哪些文件、provideFirebaseApp/provideFirestore等 provider 的底层机制以及如何用collectionData让 Firestore 数据实时流入 Angular 模板。文中所有实现细节均有仓库源码佐证可直接对照src/schematics/与src/firestore/目录深入研读。开始之前三条前置检查Quickstart 在正式动手前给出了三条容易踩坑的注意事项它们直接决定了ng add能否一次成功Firebase CLI 版本 ≥ 14。整个初始化流程由 Firebase CLIfirebase-tools驱动。ng add在你机器上没有 CLI 时会自动安装并引导你登录但不会升级已存在的旧版本。如果本机已有旧版 CLIsetup 会以firebase-tools version 14.0.0 is required, please upgrade and run again终止。提前处理或清除该错误的方法是npm install -g firebase-tools firebase login从源码看setup 阶段会通过 firebaseTools.ts 调用 CLI 的login、projects.list、apps.sdkconfig等能力旧版本缺少这些 API 就无法完成交互式初始化。新版 Angular 主版本请使用next。AngularFire 默认发布渠道latest与最新 Angular 大版本之间可能存在 peer-dependency 冲突。若ng add angular/fire报 Angular peer 依赖冲突说明你的 Angular 比 AngularFire 默认版本更新此时应安装与之匹配的预发布版本ng add angular/firenext仓库的 common.ts 还揭示了一个细节当安装的是预发布版本时schematics 会把package.json中的angular/fire声明钉死pin到精确版本因为类似^21.0.0-rc.0的预发布区间也会匹配每次 merge 到 main 后发布的 canary 构建后续安装可能静默替换掉你精心选择的版本。无害的 CLI 噪音。初始化期间 Firebase CLI 可能打印punycode弃用警告或询问是否启用额外功能例如 Gemini。这些来自 CLI 本身与 AngularFire 无关忽略即可。第一步创建 Angular 项目Quickstart 提供了两种等价方式以及一种可选的直接安装 CLI 方式# 方式一yarn create yarn create angular project-name cd project-name# 方式二npm create npm create angular project-name cd project-name# 方式三可选直接安装工具链 npm install -g angular/cli ng new project-name cd project-nameAngular CLI 的new命令会以最新版 Angular 构建一个全新的项目结构。创建过程中 CLI 会询问是否启用SSR服务端渲染这个选择会直接影响第六步的部署方式值得提前留意。第二步运行ng add angular/fire在项目根目录执行ng add angular/fire这是整个接入流程的核心。ng add会安装 AngularFire 并自动完成项目配置具体做两件事交互式提问提示你勾选要启用的功能模块、选择要使用的 Firebase 项目必要时会引导你登录 Firebase 账号。改写应用配置向应用配置如app.config.ts中注入provideFirebaseApp(...)以及每个勾选功能对应的 provider并把你的 Firebase 配置内联进去——不会创建 environment 文件。ng add底层到底改了什么理解ng add的行为最好的方式是直接看它背后的 schematics 源码入口在 src/schematics/add/index.ts首先addDependencies按peerDependencies把依赖写入package.jsonsrc/schematics/common.ts接着alignFirebaseVersion会把工作区里的firebase依赖对齐到^12.18.0这个范围见 common.ts。注释里给出了原因AngularFire 自带一份firebase依赖如果你的工作区钉在更老的 major 版本npm 会静默地在angular/fire下嵌套出第二份 SDK 副本运行时两份副本会互相拒绝对方的对象对应 issue #3684、#3681、#3682然后pinInstalledPrereleaseVersion处理上文提到的预发布版本钉死问题最后调度一个ng-add-setup-projectschematic 完成后续的交互式设置src/schematics/setup/index.ts。setup 阶段setup/index.ts的交互逻辑非常完整通过 checkbox 多选询问What features would you like to setup?可选功能在 src/schematics/interfaces.ts 中定义共 12 项Authentication、Google Analytics、App Check、Firestore、Realtime Database、Data Connect、Cloud Functions (callable)、Cloud Messaging、Performance Monitoring、Cloud Storage、Remote Config、AI Logic询问使用哪个 Firebase 账号setup/prompts.ts通过模糊搜索autocomplete选择或新建 Firebase 项目projectPrompt甚至允许直接在向导里输入 project id 创建新项目选择或新建 Web 应用appPrompt然后调用firebaseTools.apps.sdkconfig(web, ...)拉取 SDK 配置再从中筛出initializeApp()能接受的键apiKey、authDomain、databaseURL、projectId、storageBucket、messagingSenderId、appId、measurementId、recaptchaSiteKey见 setup/index.ts把选中的 Firebase 项目写入.firebaserc的projects.defaultsetup/firebaseConfigs.ts这样后续firebase命令无需再交互式选择项目如果勾选了 Firestore会自动生成测试模式test mode的firestore.rules30 天后过期与空的firestore.indexes.json并在firebase.json中注册firestore段setup/firebaseConfigs.ts如果勾选了 Data Connect还会调用firebaseTools.init(dataconnect)初始化本地配置并解析 connector SDK 生成情况。生成的 provider 是如何工作的ng add向应用配置注入的provideFirebaseApp实现在 src/app/app.module.ts。它的要点是通过makeEnvironmentProviders注册一个PROVIDED_FIREBASE_APPS多值 provider用工厂firebaseAppFactory在NgZone 之外zone.runOutsideAngular执行fn(injector)调用initializeApp(config)——这是 AngularFire 避免 Firebase 回调频繁触发变更检测的关键设计同时调用registerVersion(angularfire, VERSION.full, app)向 Firebase SDK 登记 AngularFire 版本用于问题诊断FirebaseApp的默认注入解析逻辑在defaultFirebaseAppFactory如果只显式提供了单个 app 就返回它否则回退到 Firebase SDK 的默认 appgetApp()。类似地provideFirestore在 src/firestore/firestore.module.ts 中注册Firestore实例同样在 zone 外构造并且依赖顺序上让 Auth 与 AppCheck 先于 Firestore 加载源码注释明确写着 FirestoreAuth work better if Auth is loaded first。第三步注入Firestore打开/src/app/app.ts进行如下修改import { Component, inject } from angular/core; import { AsyncPipe } from angular/common; import { Firestore } from angular/fire/firestore; Component({ selector: app-root, templateUrl: ./app.html, styleUrl: ./app.css, imports: [AsyncPipe], }) export class App { firestore: Firestore inject(Firestore); constructor() { } }Firestore类型本身定义在 src/firestore/firestore.ts它是一个接口与类的同构声明类构造器直接把底层 Firebase Firestore 实例原样返回因此你注入的Firestore本质上就是 Firebase JS SDK 的 Firestore 实例只是被 AngularFire 的 DI 体系管理起来。借助 Angular 的inject()函数组件无需构造函数参数即可拿到实例。第四步把 Firestore 集合绑定为响应式列表继续修改/src/app/app.tsimport { Component, inject } from angular/core; import { AsyncPipe } from angular/common; import { Observable } from rxjs; import { Firestore, collection, collectionData } from angular/fire/firestore; interface Item { name: string; } Component({ selector: app-root, imports: [AsyncPipe], templateUrl: ./app.html, styleUrl: ./app.css }) export class App { firestore: Firestore inject(Firestore); items$: ObservableItem[]; constructor() { const aCollection collection(this.firestore, items) this.items$ collectionDataItem(aCollection); } }再打开/src/app/app.htmlul for (item of items$ | async; track item) { li{{ item.name }}/li } /ul这里的核心是RxJS Observable AsyncPipe的数据流组合collection(this.firestore, items)创建指向items集合的引用collectionDataItem(aCollection)把该集合转换为一个发出Item[]数组的 Observable。它在 src/firestore/rxfire.ts 中通过ɵzoneWrap对 rxfire 的collectionData做了 zone 包装确保数据回调在 Angular zone 内触发变更检测模板中的items$ | async自动订阅并渲染数组for块遍历每一项输出item.name。从模块结构看angular/fire/firestore的公开 APIpublic_api.ts同时导出 AngularFire 的provideFirestore/Firestore以及 Firebase JS SDK 的全部函数collection、doc、where等见 src/firestore/firebase.ts因此你可以在 Angular 组件里直接使用熟悉的 Firebase 函数式 API。第五步本地运行ng serveAngular 应用编译并在本地提供服务后浏览器里应看到一个空列表——因为此时items集合还没有数据。在另一个终端标签页中按照 Firebase 官方文档往items集合添加数据即可。需要特别强调的是由于此时还没有接入用户认证请务必将 Firestore 以**测试模式test mode**启动或在安全规则中允许读取items集合allow read: if true否则数据读取会被规则拦截。一旦你创建了items集合并开始插入文档就会看到数据实时流入 Angular 应用并渲染在浏览器中——这正是collectionData订阅 onSnapshot 实时监听带来的效果。测试模式规则提醒如果你是用ng add勾选 Firestore 完成初始化的schematics 生成的 firestore.rules 本身就是测试模式允许任何人读写但30 天后过期之后所有客户端请求都会被拒绝setup/firebaseConfigs.ts。因此上线前务必把安全规则替换为正式的鉴权规则。第六步部署应用部署方式取决于应用是否使用了 SSR服务端渲染——Angular CLI 创建项目时会询问这一项。纯客户端渲染应用默认构建产物是静态文件部署到 Firebase Hosting。请按 Firebase 官方 Hosting quickstart 构建并部署应用也可以使用本仓库提供的部署 builderangular/fire的 schematics 中内置了 deploy 支持见 src/schematics/deploy/builder.ts。SSR 应用运行的是 Node 服务器因此建议部署到Firebase App Hosting——这也是 Firebase 对 SSR 场景推荐的路径。完整的部署步骤见 Firebase App Hosting 指南该指南还覆盖了一个常见坑SSR 应用部署后静默回退到客户端渲染例如服务器端数据获取失败、Node 运行环境缺失等导致需要按指南逐一排查。仓库的示例应用 sample/src/app/app.config.ts 展示了生产级配置的形态provideZonelessChangeDetection()、provideClientHydration(withIncrementalHydration())与provideAuth(...)组合使用并演示了如何在 provider 工厂里判断_canInitEmulator后连接 Auth 模拟器——可作为你初始化完成后进一步接入各模块的参考模板。常见问题速查现象原因处理方式firebase-tools version 14.0.0 is required本机 CLI 版本过旧ng add不会自动升级npm install -g firebase-tools后firebase loginAngular peer-dependency 冲突Angular 比 AngularFire 默认 release 更新ng add angular/firenextpunycode弃用警告 / 询问启用 GeminiFirebase CLI 自身行为忽略即可浏览器列表为空items集合尚无数据或安全规则拦截读取测试模式下添加数据或放行items的 read 规则测试模式规则过期后数据全部被拒生成的 rules 30 天后过期提前替换为正式安全规则npm 安装了双份 firebase SDK 导致运行时互相拒绝对象工作区firebase版本与 AngularFire 要求的^12.18.0范围不符重新运行ng add让alignFirebaseVersion对齐版本小结从yarn create angular到ng add angular/fire再到inject(Firestore)与collectionData的响应式绑定整个过程被 AngularFire 的 schematics 高度自动化它不仅写好了 provider还会同步管理firebase.json、.firebaserc、firestore.rules等配套文件。理解 src/schematics/add/index.ts 与 src/schematics/setup/index.ts 的实现能让你在遇到版本对齐、规则过期、双 SDK 副本等边缘问题时快速定位根因。后续深入某个模块Auth、Storage、Functions 等时各模块目录下的*.module.ts与rxfire.ts都遵循与 Firestore 相同的 provider zone 包装模式可以举一反三。赞分享后端【免费下载链接】angularfireAngular Firebase ❤️项目地址https://gitcode.com/gh_mirrors/an/angularfire点击查看免费下载相关推荐Angular Material 快速入门从 ng add 安装到首个组件实战Angular Material 快速入门从 ng add 安装到首个组件实战 本篇技术指南以官方文档 guides/getting started.md h前端UI组件设计系统MikroORM 快速上手指南从安装初始化到实体定义与数据持久化v5.9MikroORM 快速上手指南从安装初始化到实体定义与数据持久化v5.9 本篇指南基于 MikroORM v5.9 版本文档 quick start.md后端Rerun 点云渲染优化从 8fps 到 35fps 的三步路径与一份可照做的检查单Rerun 点云渲染优化从 8fps 到 35fps 的三步路径与一份可照做的检查单 Rerun 是机器人 LiDAR、三维重建等多模态数据常用的可视化工具。后端上一篇3分钟解锁Beyond Compare 5开源密钥生成工具完整指南下一篇3分钟永久激活Beyond Compare 5开源密钥生成器终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考