升級至 Node.js SDK Admin SDK v10 (模組 SDK)

Admin Node.js SDK 第 10 版導入了兩項重要變更：

  • 停止支援 Node.js 10 (這項異動屬於重大變更)
  • SDK 採用模組化 API 模式

本指南提供操作說明和資訊，協助開發人員將現有的 Node.js 應用程式從舊版 Admin SDK 升級至 v10。

將 Node.js 更新至 12 以上版本

隨著 Admin Node.js SDK 第 10 版發布，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');

自第 10 版起，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 開發人員不必再使用三重巢狀類型 ID，例如 admin.auth.UserRecord 和 admin.database.Reference。由於每個型別都只屬於一個模組，因此您只要使用簡短名稱 (例如 UserRecord 和 Reference) 匯入即可。

以下是 SDK 第 10 版提供的所有模組進入點：

  • 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();

使用匯出的函式，而非 App 上的方法

在舊版 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。

如要搭配 Admin SDK 使用 ES 模組，請先確認已為 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');