升级到 Node.js SDK Admin SDK v10(模块化 SDK)

Admin Node.js SDK 版本 10 引入了两项重要变更:

  • 不再支持 Node.js 10(这是一项重大变更
  • SDK 采用了模块化 API 模式

本指南提供了说明和信息,可帮助开发者将现有 Node.js 应用从早期版本的 Admin SDK 升级到 v10。

将 Node.js 更新为 v12 或更高版本

在 Admin Node.js SDK v10 版本中,Firebase 已停止支持 Node.js 10。使用 Admin SDK 时,开发者必须使用 Node.js 12 或更高版本。如果您将 Admin Node.js SDK 与 Cloud Functions for Firebase 搭配使用,请确保您已将 Node.js 版本升级到 12 或更高版本。

使用模块代替命名空间

自问世以来,Admin Node.js SDK 提供了一个稳定的 API,其结构为嵌套的命名空间层次结构。因此,您可能已熟悉如何编写如下所示的代码:

// Import the global admin namespace
import * as admin from 'firebase-admin';

const app: admin.app.App = admin.initializeApp();

const token: string = await admin.auth().createCustomToken('alice');

const user: admin.auth.UserRecord = await admin.auth().getUser('bob');

从 v10 开始,Admin Node.js SDK 提供了多个包含已命名导出内容的模块入口点。我们建议开发者使用这些新入口点访问 SDK 的各种 API,而不是使用全局 admin 命名空间。

使用新模块入口点后,上面的示例将如下所示:

TypeScript

// Import only what you need
import { initializeApp, App } from 'firebase-admin/app';
import { getAuth, UserRecord } from 'firebase-admin/auth';

const app: App = initializeApp();

const token: string = await getAuth().createCustomToken('alice');

const user: UserRecord = getAuth().getUser('bob');

Node.js

// Import only what you need
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');

使用 v10 模块化入口点

请注意,在上面的示例中,您不再导入全局 admin 命名空间,而是仅从多个模块入口点明确导入所需的符号。此外,TypeScript 开发者不再需要使用三重嵌套类型标识符,例如 admin.auth.UserRecordadmin.database.Reference。由于每种类型都只属于一个模块,因此您只需按其简称(如 UserRecordReference)导入它们即可。

以下是自 v10 起的 SDK 中提供的所有模块入口点:

  • firebase-admin/app
  • firebase-admin/auth
  • firebase-admin/database
  • firebase-admin/firestore
  • firebase-admin/instance-id
  • firebase-admin/machine-learning
  • firebase-admin/messaging
  • firebase-admin/project-management
  • firebase-admin/remote-config
  • firebase-admin/security-rules
  • firebase-admin/storage

下表显示了每个旧版命名空间函数的替换导入语法:

v9 v10
admin.initializeApp() import { initializeApp } from 'firebase-admin/app'

initializeApp();

admin.app() import { getApp } from 'firebase-admin/ap'

getApp();

admin.credential.cert() import { cert } from 'firebase-admin/app'

cert();

admin.auth() import { getAuth } from 'firebase-admin/auth'

getAuth();

admin.database() import { getDatabase } from 'firebase-admin/database'

getDatabase();

admin.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore();

admin.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId();

admin.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning();

admin.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging()

admin.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement();

admin.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig();

admin.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules()

admin.storage() import { getStorage } from 'firebase-admin/storage'

getStorage();

在应用中使用导出的函数而不是方法

在旧版 API 中,App 对象公开了许多方法,如 app.auth()app.database()。我们建议开发者避免使用这些方法,而改用上述模块入口点来获取作用域限定为给定 App 对象的服务实例,并执行其他应用特有的任务。

v9 v10
app.auth() import { getAuth } from 'firebase-admin/auth';

getAuth(app);

app.database() import { getDatabase } from 'firebase-admin/database';

getDatabase(app);

app.database(url) import { getDatabaseWithUrl } from 'firebase-admin/database';

getDatabaseWithUrl(url, app);

app.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore(app);

app.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId(app);

app.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning(app);

app.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging(app);

app.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement(app);

app.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig(app);

app.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules(app);

app.storage() import { getStorage } from 'firebase-admin/storage'

getStorage(app);

app.delete() import { deleteApp } from 'firebase-admin/app';

deleteApp(app);

ES 模块支持

Node.js 12 及更高版本提供对 ES 模块的实验性支持,即便是非 TypeScript 开发者,也可以在其代码中使用 exportimport 关键字。从 v10 版本开始,Admin Node.js SDK 还提供 ES 模块支持,因此通过纯 Node.js 实现 ES 模块的开发者可以使用 import 语法导入 SDK。

如需将 Admin 模块与 Admin SDK 搭配使用,请先确保您已为 Node.js 运行时启用了 ESM 支持。这通常是通过向 package.json 文件添加 "type": "module" 字段来完成的。那么,您可以编写如下所示的应用代码:

// With {type: module} in the package.json...

// Import only what you need
import { initializeApp }  from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');