升级到 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 命名空间。

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

TypeScriptNode.js
// 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');

// 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.UserRecord 和 admin.database.Reference。由于每种类型都只属于一个模块，因此您只需按其简称（如 UserRecord 和 Reference）导入它们即可。

以下是自 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 开发者，也可以在其代码中使用 export 和 import 关键字。从 v10 版本开始，Admin Node.js SDK 还提供 ES 模块支持，因此通过纯 Node.js 实现 ES 模块的开发者可以使用 import 语法导入 SDK。

如需将 ES 模块与 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');