移动 SDK 和 Web SDK 使用入门

此快速入门将向您展示如何设置 Cloud Firestore、添加数据以及在 Firebase 控制台中查看您刚添加的数据。

Cloud Firestore 支持移动 SDK 或 Web SDK 和服务器客户端库：

  • Cloud Firestore 支持 Android、iOS、Web 等平台的 SDK。与 Cloud Firestore Security Rules 和 Firebase Authentication 结合使用时，移动 SDK 和 Web SDK 支持无服务器应用架构，客户端可直接连接到您的 Cloud Firestore 数据库。
  • Cloud Firestore 支持 C#、Go、Java、Node.js、PHP、Python 和 Ruby 语言的服务器客户端库。使用这些客户端库设置特权服务器环境，以便全面访问您的数据库。如需详细了解这些库，请参阅服务器客户端库快速入门。

创建 Cloud Firestore 数据库

  1. 如果您还没有 Firebase 项目，请创建一个，具体步骤是：在 Firebase 控制台中，点击添加项目，然后按照屏幕上的说明创建 Firebase 项目或将 Firebase 服务添加到现有 Google Cloud 项目。
  2. 在 Firebase 控制台中打开您的项目。在左侧面板中，展开构建，然后选择 Firestore 数据库。
  3. 点击创建数据库。
  4. 选择数据库的位置。

如果您无法选择位置，则表明项目的“默认 Google Cloud 资源位置”已经设置。您的项目的部分资源（例如默认 Cloud Firestore 实例）共享一个通用位置依赖项，并且可以在项目创建期间或设置共享此位置依赖项的其他服务时设置其位置。 5. 为您的 Cloud Firestore Security Rules选择一个初始模式：

测试模式 : 此模式适合刚开始使用移动和 Web 客户端库的用户，但会允许任何人读取和覆盖您的数据。测试完成后，请务必查看保护您的数据部分。 : 如需开始使用 Web、Apple 平台或 Android SDK，请选择测试模式。

生产模式 : 拒绝来自移动和 Web 客户端的所有读写操作。经过身份验证的应用服务器（C#、Go、Java、Node.js、PHP、Python 或 Ruby）仍然可以访问您的数据库。 : 如需开始使用 C#、Go、Java、Node.js、PHP、Python 或 Ruby 服务器客户端库，请选择生产模式。

最初的一组 Cloud Firestore Security Rules将应用于您的默认 Cloud Firestore 数据库。如果您为项目创建多个数据库，则可以为每个数据库部署 Cloud Firestore Security Rules。 6. 点击创建。

启用 Cloud Firestore 时，也会在 Cloud API 管理器中启用相应 API。

设置开发环境

将所需的依赖项和客户端库添加到您的应用。

Web

  1. 按照相关说明将 Firebase 添加到您的 Web 应用。
  2. Cloud Firestore SDK 可以作为 npm 软件包提供。

npm install firebase@12.11.0 --save

您需要导入 Firebase 和 Cloud Firestore。

import { initializeApp } from "firebase/app"; import { getFirestore } from "firebase/firestore";

Web

  1. 按照相关说明将 Firebase 添加到您的 Web 应用。
  2. 将 Firebase 库和 Cloud Firestore 库添加到您的应用中：

```

```

Cloud Firestore SDK 也可以作为 npm 软件包提供。

npm install firebase@12.11.0 --save

您需要手动对 Firebase 和 Cloud Firestore 执行 require 方法。

import firebase from "firebase/compat/app"; // Required for side-effects import "firebase/firestore";

iOS+

按照相关说明将 Firebase 添加到您的 Apple 应用。

使用 Swift Package Manager 安装和管理 Firebase 依赖项。

  1. 在 Xcode 中打开您的应用项目，依次点击 File（文件）> Swift Packages（Swift 软件包）> Add Package Dependency（添加软件包依赖项）。
  2. 出现提示时，添加 Firebase Apple 平台 SDK 仓库：
  https://github.com/firebase/firebase-ios-sdk
  1. 选择 Firestore 库。
  2. 完成之后，Xcode 将会自动开始在后台解析和下载您的依赖项。
Android
  1. 按照相关说明将 Firebase 添加到您的 Android 应用。
  2. 使用 Firebase Android BoM 在模块（应用级）Gradle 文件（通常是 app/build.gradle.kts 或 app/build.gradle）中声明 Cloud Firestore Android 库的依赖项。

``` dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:34.11.0"))

   // Declare the dependency for the Cloud Firestore library
   // When using the BoM, you don't specify versions in Firebase library dependencies
   implementation("com.google.firebase:firebase-firestore")

} ```

借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

（替代方法） 在不使用 BoM 的情况下声明 Firebase 库依赖项

如果您选择不使用 Firebase BoM，则必须在每个 Firebase 库的依赖项行中指定相应的库版本。

请注意，如果您在应用中使用多个 Firebase 库，我们强烈建议您使用 BoM 来管理库版本，从而确保所有版本都兼容。

dependencies { // Declare the dependency for the Cloud Firestore library // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-firestore:26.1.2") }

是否想要查找 Kotlin 专用的库模块？从 2023 年 10 月发布的版本开始，Kotlin 和 Java 开发者可以依赖于主库模块（如需了解详情，请参阅关于此计划的常见问题解答）。

Dart

  1. 在 Flutter 应用中配置并初始化 Firebase（如果尚未执行此操作）。
  2. 从 Flutter 项目的根目录运行以下命令，安装该插件：

flutter pub add cloud_firestore 3. 完成后，重新构建您的 Flutter 应用：

flutter run 4. 可选：通过添加预编译框架来缩短 iOS 和 macOS 构建时间。

目前，iOS 版 Firestore SDK 所依赖的代码可能需要长达 5 分钟时间才能在 Xcode 中构建完毕。如需显著缩短构建时间，您可以使用预编译版本，只需将下面的代码添加到 Podfile 的 target 'Runner' do 代码块中即可：

``` target 'Runner' do use_frameworks! use_modular_headers!

 pod 'FirebaseFirestore',
   :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
   :tag => 'IOS_SDK_VERSION'

 flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
 target 'RunnerTests' do
   inherit! :search_paths
 end

end ```

将 IOS_SDK_VERSION 替换为 firebase_core 的 firebase_sdk_version.rb 文件中指定的 Firebase iOS SDK 版本。如果您使用的不是最新版本的 firebase_core，请在本地 Pub 软件包缓存（通常为 ~/.pub-cache）中查找此文件。

此外，请确保您已将 CocoaPods 升级到 1.9.1 或更高版本：

gem install cocoapods

如需了解详情，请参阅 GitHub 上的问题。

C++
  1. 按照相关说明将 Firebase 添加到您的 C++ 项目。

  2. Android 版 C++ 接口。

  3. Gradle 依赖项。将以下内容添加到您的模块（应用级）Gradle 文件（通常为 app/build.gradle）：

``` android.defaultConfig.externalNativeBuild.cmake { arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir" }

      apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
      firebaseCpp.dependencies {
        // earlier entries
        auth
        firestore
      }

`` - **二进制依赖项**。同样，建议用来获取二进制依赖项的方法是将以下内容添加到CMakeLists.txt` 文件中：

add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL) set(firebase_libs firebase_auth firebase_firestore firebase_app) # Replace the target name below with the actual name of your target, # for example, "native-lib". target_link_libraries(${YOUR_TARGET_NAME_HERE} "${firebase_libs}")

  1. 如需设置桌面集成，请参阅将 Firebase 添加到您的 C++ 项目。
Unity
  1. 按照相关说明将 Firebase 添加到您的 Unity 项目。
  2. 使用 Unity 界面配置您的项目以缩减 Android build 的大小。

您必须缩减 build 的大小以避免出现消息 Error while merging dex archives。

  • 可在 Player Settings > Android > Publishing Settings > Minify 中找到该选项。
  • 这些选项可能会因 Unity 的不同版本而异，因此请参阅官方 Unity 文档和 Firebase Unity Build 调试指南。
  • 如果在启用缩减大小后，引用的方法数量仍然超过上限，另一种方法是在以下位置启用 multidex：
  • mainTemplate.gradle（如果启用了 Player Settings 下的 Custom Gradle Template）
  • 模块级 build.gradle 文件（如果您使用 Android Studio 构建导出的项目）。

（可选）使用 Firebase Local Emulator Suite 进行原型设计和测试

对于移动开发者，在介绍应用如何对 Cloud Firestore 执行读写操作之前，我们先介绍一套可用于对 Cloud Firestore 功能进行原型设计和测试的工具：Firebase Local Emulator Suite。如果您在尝试使用不同的数据模型、优化安全规则，或设法寻找最经济有效的方式与后端进行交互，那么无需实际部署即可在本地进行上述工作是非常理想的。

Cloud Firestore 模拟器是 Local Emulator Suite 的一部分，通过该模拟器，您的应用可以与模拟的数据库内容和配置进行交互，并可视需要与您的模拟项目资源（函数、其他数据库和安全规则）进行交互。

如需使用 Cloud Firestore 模拟器，只需完成几个步骤：

  1. 向应用的测试配置添加一行代码以连接到模拟器。
  2. 从本地项目的根目录运行 firebase emulators:start。
  3. 照常使用 Cloud Firestore 平台 SDK 从应用的原型设计代码进行调用。

我们提供详细的 Cloud Firestore 和 Cloud Functions 演示。您还应该参阅 Local Emulator Suite 简介。

初始化 Cloud Firestore

初始化 Cloud Firestore 的实例：

Web

import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
    FIREBASE_CONFIGURATION
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);

// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);

将 FIREBASE_CONFIGURATION 替换为 Web 应用的 firebaseConfig。

如需在设备的网络连接中断时保留数据，请参阅启用离线数据文档。

Web

import firebase from "firebase/app";
import "firebase/firestore";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
    FIREBASE_CONFIGURATION
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

// Initialize Cloud Firestore and get a reference to the service
const db = firebase.firestore();

将 FIREBASE_CONFIGURATION 替换为 Web 应用的 firebaseConfig。

如需在设备的网络连接中断时保留数据，请参阅启用离线数据文档。

Swift

注意：此产品不适用于 watchOS 和 App Clip 目标。

import FirebaseCore
import FirebaseFirestore

FirebaseApp.configure()

let db = Firestore.firestore()

AppDelegate.swift
Objective-C

注意：此产品不适用于 watchOS 和 App Clip 目标。

@import FirebaseCore;
@import FirebaseFirestore;

// Use Firebase library to configure APIs
[FIRApp configure];

FIRFirestore *defaultFirestore = [FIRFirestore firestore];

AppDelegate.m

Kotlin

// Access a Cloud Firestore instance from your Activity

val db = Firebase.firestore

DocSnippets

.kt