從命名空間 API 升級至模組 API

目前使用 compat 程式庫中的任何命名空間 Firebase Web API 的應用程式 到第 8 版或更舊版本，請考慮 按照本指南的操作說明遷移至模組 API。

本指南假設 您熟悉命名空間 API 之後 例如 webpack 或 匯總：升級和升級 持續進行模組化應用程式開發作業

強烈建議您在開發環境中使用模組整合工具 建議如果沒有使用，就無法充分運用 縮減應用程式大小。你需要準備 npm 或 yarn 安裝 SDK。

本指南中的升級步驟是以 使用 Authentication 和 Cloud Firestore SDK透過這些範例 能夠掌握升級所有支援項目所需的概念和實用步驟 Firebase Web SDK。

關於命名空間 (compat) 程式庫

Firebase Web SDK 有兩種程式庫類型：

• 模組化 - 專為協助樹動樹而設計的全新 API 介面 (移除未使用的程式碼) 至 盡可能加快網頁應用程式的大小
• 命名空間 (compat) - 熟悉的 API 介面 可與 Google Kubernetes Engine SDK 的較舊版本，您可以直接升級，不必變更 Firebase 程式碼只要使用 Compat 程式庫 沒有大小或成效 勝過各自的命名空間

本指南假設您會善用相容性 加速升級的程式庫這些程式庫可讓您 。這代表您 可以在升級期間更輕鬆地編譯及偵錯應用程式 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作

注意事項：Compat 程式庫只是暫時性的 未來的主要 SDK 版本將完全移除的解決方案 (例如 第 10 版或第 11 版)。最終目標是移除相容性程式碼 並只保留模組化樣式的程式碼。

對 Firebase Web SDK 很少使用的應用程式 (例如 只對 Authentication API 進行簡單的呼叫的應用程式 (可能 非常實用的做法，可在不使用 Compat 程式庫的情況下，重構較舊的命名空間程式碼。 如果您要升級這類應用程式，請按照本指南的說明操作 關於「模組化 API」不必使用 Compat 程式庫

關於升級程序

升級程序的每個步驟都設有範圍，方便您完成升級作業 ，然後編譯並執行應用程式，不會造成中斷。總結來說 升級應用程式的步驟如下：

1. 將模組化程式庫和 Compat 程式庫新增至應用程式。
2. 更新程式碼中的匯入陳述式，以便遵守規範。
3. 重構單一產品 (例如 Authentication) 的程式碼： 以及模組樣式
4. 選用：此時，移除 Authentication Compat 程式庫和 Compat 程式碼 Authentication，以便 繼續前，請先瞭解「Authentication」的應用程式大小優勢。
5. 重構每個產品的函式 (例如 Cloud Firestore、FCM 等) 對應至模組樣式、編譯和 並進行測試。
6. 將初始化程式碼更新為模組樣式。
7. 從以下項目移除所有其餘的 Compat 陳述式和 Compat 程式碼

取得最新版 SDK

如要開始使用，請使用 npm 取得模組化程式庫和 Compat 程式庫：

npm i firebase@10.13.1

# OR

yarn add firebase@10.13.1

將匯入項目更新為相容版本

更新依附元件後，為了保持程式碼正常運作， 請更改匯入陳述式，改用「compat」 的每個匯入版本例如：

變更前：8 以下版本

import firebase from 'firebase/app';
import 'firebase/auth';
import 'firebase/firestore';

變更後：相容性

// compat packages are API compatible with namespaced code
import firebase from 'firebase/compat/app';
import 'firebase/compat/auth';
import 'firebase/compat/firestore';

重構為模組樣式

命名空間 API 是以點鏈命名空間和服務為基礎 模組化的做法 意味著系統會整理程式碼 主要為函式在模組化 API 中，firebase/app 套件和 其他套件不會傳回 方法中。而是會匯出個別函式。

在模組化 API 中，服務會做為第一個引數傳遞，接著函式 會使用服務詳細資料來執行其他程序。接著來看看如何在 會重構對 Authentication 和 Cloud Firestore API 的呼叫。

範例 1：重構 Authentication 函式

變更前：相容性

compat 程式碼與命名空間程式碼相同，但匯入作業 已有所變更。

import firebase from "firebase/compat/app";
import "firebase/compat/auth";

const auth = firebase.auth();
auth.onAuthStateChanged(user => { 
  // Check for user status
});

變更後：模組化

getAuth 函式使用 firebaseApp 做為第一個參數。 onAuthStateChanged 函式未與 auth 執行個體鏈結不同 命名空間；因為這需要 函式，以 auth 做為第一個參數。

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

更新驗證方法「getRedirectResult」的處理方式

注意： 如果您的應用程式使用驗證方法 getRedirectResult，您就必須更新 。無法重構程式碼 應用程式可能會發生無法預測的行為。

模組化 API 會在 getRedirectResult 中導入破壞性變更。如未呼叫任何重新導向作業，模組化 API 會傳回 null，而非命名空間 API，後者會傳回包含 null 使用者的 UserCredential。

變更前：相容性

const result = await auth.getRedirectResult()
if (result.user === null && result.credential === null) {
  return null;
}
return result;

變更後：模組化

const result = await getRedirectResult(auth);
// Provider of the access token could be Facebook, Github, etc.
if (result === null || provider.credentialFromResult(result) === null) {
  return null;
}
return result;

範例 2：重構 Cloud Firestore 函式

變更前：相容性

import "firebase/compat/firestore"

const db = firebase.firestore();
db.collection("cities").where("capital", "==", true)
    .get()
    .then((querySnapshot) => {
        querySnapshot.forEach((doc) => {
            // doc.data() is never undefined for query doc snapshots
            console.log(doc.id, " => ", doc.data());
        });
    })
    .catch((error) => {
        console.log("Error getting documents: ", error);
    });

變更後：模組化

getFirestore 函式使用 firebaseApp 做為第一個參數， 是在先前的範例中從 initializeApp 傳回。請注意 構成查詢的程式碼在模組化 API 中大不相同不會有鏈結 query 或 where 等方法現在會公開為免費函式。

import { getFirestore, collection, query, where, getDocs } from "firebase/firestore";

const db = getFirestore(firebaseApp);

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q);
querySnapshot.forEach((doc) => {
  // doc.data() is never undefined for query doc snapshots
  console.log(doc.id, " => ", doc.data());
});

更新 Firestore「DocumentSnapshot.exists」的參照設定

注意： 如果您的應用程式使用 DocumentSnapshot.exists 屬性，您必須 執行本節所述的更新程序。無法重構程式碼 應用程式可能會發生無法預測的行為。

模組化 API 導入了屬性的破壞性變更 firestore.DocumentSnapshot.exists 已變更為方法。 功能大致相同 (測試文件是否存在) 但您必須重構程式碼才能使用新方法，如下所示：

Before:compat

if (snapshot.exists) {
  console.log("the document exists");
}

變更後：模組化

if (snapshot.exists()) {
  console.log("the document exists");
}

範例 3：結合命名空間和模組化程式碼樣式

在升級期間使用 Compat 程式庫可讓您繼續使用命名空間 以及重構模組化 API 的程式碼也就是說 重構 Authentication 時，Cloud Firestore 的現有命名空間程式碼 或其他 Firebase SDK 程式碼 互動，並繼續使用這兩種程式碼成功編譯應用程式 。在產品「內」建立命名空間和模組化 API 程式碼時也是如此。 如同 Cloud Firestore；新舊程式碼樣式可以同時存在 匯入 Compat 套件：

import firebase from 'firebase/compat/app';
import 'firebase/compat/firestore';
import { getDoc } from 'firebase/firestore'

const docRef = firebase.firestore().doc();
getDoc(docRef);

請注意，雖然您的應用程式會編譯，但您無法取得應用程式大小 直到您完全移除 compat 陳述式並 擷取及轉換程式碼

更新初始化程式碼

如要使用模組語法，請更新應用程式的初始化程式碼。是 重構所有 只載入應用程式的程式碼這是因為 firebase.initializeApp() 會在全域值之間 模型和模組 API 狀態，而模組化 initializeApp() 函式只會初始化模組狀態。

變更前：相容性

import firebase from "firebase/compat/app"

firebase.initializeApp({ /* config */ });

變更後：模組化

import { initializeApp } from "firebase/app"

const firebaseApp = initializeApp({ /* config */ });

移除 Compat 程式碼

為了發揮模組化 API 的大小效益，最終您應該 將所有叫用轉換為上方所示的模組化樣式，並移除所有 程式碼中的 import "firebase/compat/* 陳述式。建立完成後 不應再參照 firebase.* 全域命名空間或任何其他 命名空間

從視窗中使用 Compat 程式庫

模組化 API 經過最佳化調整，適用於模組，而非瀏覽器的 window 物件。舊版程式庫允許載入 藉此管理 Firebase 的window.firebase命名空間。這並不是 因為不允許刪除未使用的程式碼。 不過，JavaScript SDK 的 Compat 版本可與 window 搭配使用 。

<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-firestore-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.13.1/firebase-auth-compat.js"></script>
<script>
   const firebaseApp = firebase.initializeApp({ /* Firebase config */ });
   const db = firebaseApp.firestore();
   const auth = firebaseApp.auth();
</script>

相容性程式庫會在內部使用模組化程式碼 提供的 API 與命名空間 API 相同也就是說 請參閱命名空間 API 參考資料 和命名空間程式碼片段這個方法 建議長期使用，不過您也可以先升級至完全模組化 資源庫。

模組化 SDK 的優點和限制

完全模組化的 SDK 有以下優點：

• 模組 SDK 能大幅縮減應用程式大小。 採用新式 JavaScript 模組格式，允許「樹動搖晃」實務做法 僅提供應用程式所需的構件視您的應用程式而定 與模組 SDK 進行樹狀結構時 透過命名空間 API 建構的類似應用程式。
• 模組化 SDK 可持續受益於功能開發工作。 命名空間 API 則不會