升级到 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.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');
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-12。
[null,null,["最后更新时间 (UTC):2025-08-12。"],[],[],null,["\u003cbr /\u003e\n\nVersion 10 of the Admin Node.js SDK introduces two important changes:\n\n- Support for Node.js 10 is discontinued (this is a **breaking change**)\n- The SDK has adopted a modular API pattern\n\nThis guide provides instructions and information to help developers upgrade\nexisting Node.js apps from earlier versions of the Admin SDK to v10.\n\nUpdate Node.js to v12 or higher\n\nWith the Admin Node.js SDK v10 release, Firebase has discontinued support for\nNode.js 10. Developers must use Node.js 12 or higher when using the Admin SDK.\nIf you're using the Admin Node.js SDK together with Cloud Functions for Firebase,\nmake sure that you have\n[upgraded your Node.js version](/docs/functions/manage-functions#upgrade-node10)\nto 12 or higher.\n\nUse modules instead of namespaces\n\nSince its inception, the Admin Node.js SDK has offered a stable API structured\nas a nested namespace hierarchy. As a result, you might have become familiar\nwith writing code that looks like this: \n\n // Import the global admin namespace\n import * as admin from 'firebase-admin';\n\n const app: admin.app.App = admin.initializeApp();\n\n const token: string = await admin.auth().createCustomToken('alice');\n\n const user: admin.auth.UserRecord = await admin.auth().getUser('bob');\n\nStarting from v10, the Admin Node.js SDK offers multiple module entry points\nwith named exports. We recommend developers to use these new entry points to\naccess the various APIs of the SDK, as opposed to using the global `admin`\nnamespace.\n\nHere's what the above example would look like with the new module\nentry points: \n\nTypeScript \n\n // Import only what you need\n import { initializeApp, App } from 'firebase-admin/app';\n import { getAuth, UserRecord } from 'firebase-admin/auth';\n\n const app: App = initializeApp();\n\n const token: string = await getAuth().createCustomToken('alice');\n\n const user: UserRecord = getAuth().getUser('bob');\n\nNode.js \n\n // Import only what you need\n const { initializeApp } = require('firebase-admin/app');\n const { getAuth } = require('firebase-admin/auth');\n\n const app = initializeApp();\n\n const token = await getAuth().createCustomToken('alice');\n\n const user = getAuth().getUser('bob');\n\nUsing v10 modular entry points\n\nNote that, in the examples above, you are no longer importing a global `admin`\nnamespace. Instead, you explicitly import only the symbols you need from several\nmodule entry points. Also, TypeScript developers no longer have to use triple-\nnested type identifiers like `admin.auth.UserRecord` and\n`admin.database.Reference`. Since each type belongs to exactly one module, you\ncan just import them by their short names like `UserRecord` and `Reference`.\n\nHere are all the module entry points available in the SDK as of v10:\n\n- firebase-admin/app\n- firebase-admin/auth\n- firebase-admin/database\n- firebase-admin/firestore\n- firebase-admin/instance-id\n- firebase-admin/machine-learning\n- firebase-admin/messaging\n- firebase-admin/project-management\n- firebase-admin/remote-config\n- firebase-admin/security-rules\n- firebase-admin/storage\n\nThe following table shows the replacement import syntax for each of the legacy\nnamespace functions:\n\n| **v9** | **v10** |\n|-----------------------------|------------------------------------------------------------------------------------------------------|\n| `admin.initializeApp()` | `import { initializeApp } from 'firebase-admin/app'` `initializeApp();` |\n| `admin.app()` | `import { getApp } from 'firebase-admin/ap'` `getApp();` |\n| `admin.credential.cert()` | `import { cert } from 'firebase-admin/app'` `cert();` |\n| `admin.auth()` | `import { getAuth } from 'firebase-admin/auth'` `getAuth();` |\n| `admin.database()` | `import { getDatabase } from 'firebase-admin/database'` `getDatabase();` |\n| `admin.firestore()` | `import { getFirestore } from 'firebase-admin/firestore'` `getFirestore();` |\n| `admin.instanceId()` | `import { getInstanceId } from 'firebase-admin/instance-id'` `getInstanceId();` |\n| `admin.machineLearning()` | `import { getMachineLearning } from 'firebase-admin/machine-learning'` `getMachineLearning();` |\n| `admin.messaging()` | `import { getMessaging } from 'firebase-admin/messaging'` `getMessaging()` |\n| `admin.projectManagement()` | `import { getProjectManagement } from 'firebase-admin/project-management'` `getProjectManagement();` |\n| `admin.remoteConfig()` | `import { getRemoteConfig } from 'firebase-admin/remote-config'` `getRemoteConfig();` |\n| `admin.securityRules()` | `import { getSecurityRules } from 'firebase-admin/security-rules'` `getSecurityRules()` |\n| `admin.storage()` | `import { getStorage } from 'firebase-admin/storage'` `getStorage();` |\n\nUse exported functions instead of methods on App\n\nIn the legacy API, the `App` object exposed a number of methods like\n`app.auth()` and `app.database()`. We recommend developers to avoid using these\nmethods, and instead use the same module entry points described above to obtain\nservice instances scoped to a given `App` object, and perform other app-specific\ntasks.\n\n| **v9** | **v10** |\n|---------------------------|---------------------------------------------------------------------------------------------------------|\n| `app.auth()` | `import { getAuth } from 'firebase-admin/auth';` `getAuth(app);` |\n| `app.database()` | `import { getDatabase } from 'firebase-admin/database';` `getDatabase(app);` |\n| `app.database(url)` | `import { getDatabaseWithUrl } from 'firebase-admin/database';` `getDatabaseWithUrl(url, app);` |\n| `app.firestore()` | `import { getFirestore } from 'firebase-admin/firestore'` `getFirestore(app);` |\n| `app.instanceId()` | `import { getInstanceId } from 'firebase-admin/instance-id'` `getInstanceId(app);` |\n| `app.machineLearning()` | `import { getMachineLearning } from 'firebase-admin/machine-learning'` `getMachineLearning(app);` |\n| `app.messaging()` | `import { getMessaging } from 'firebase-admin/messaging'` `getMessaging(app);` |\n| `app.projectManagement()` | `import { getProjectManagement } from 'firebase-admin/project-management'` `getProjectManagement(app);` |\n| `app.remoteConfig()` | `import { getRemoteConfig } from 'firebase-admin/remote-config'` `getRemoteConfig(app);` |\n| `app.securityRules()` | `import { getSecurityRules } from 'firebase-admin/security-rules'` `getSecurityRules(app);` |\n| `app.storage()` | `import { getStorage } from 'firebase-admin/storage'` `getStorage(app);` |\n| `app.delete()` | `import { deleteApp } from 'firebase-admin/app';` `deleteApp(app);` |\n\nES modules support\n\nNode.js 12 and above come with experimental support for ES modules, enabling\neven non-TypeScript developers to use the `export` and `import` keywords in\ntheir code. Starting from the v10 release, the Admin Node.js SDK also provides\nES modules support, so that developers implementing ES modules on plain Node.js\ncan import the SDK using `import` syntax.\n\nTo use ES modules with the Admin SDK, first make sure you have enabled ESM\nsupport for your Node.js runtime. This is usually done by adding a `\"type\":\n\"module\"` field to your `package.json` file. Then you can write application code\nthat looks like this: \n\n // With {type: module} in the package.json...\n\n // Import only what you need\n import { initializeApp } from 'firebase-admin/app';\n import { getAuth } from 'firebase-admin/auth';\n\n const app = initializeApp();\n\n const token = await getAuth().createCustomToken('alice');\n\n const user = getAuth().getUser('bob');"]]