轉換至瀏覽器命名空間

從 Chrome 148 開始，除了現有的 chrome 命名空間，所有 Chrome 擴充功能 API 都可在 browser 命名空間下使用。舉例來說，browser.tabs.create({}) 和 chrome.tabs.create({}) 是等效的。

您可以在任何可呼叫擴充功能 API 的位置使用命名空間，包括內容指令碼、服務工作人員和螢幕外文件。它指向的 API 物件與 chrome 相同，因此 chrome.tabs === browser.tabs。

browser 命名空間是 WebExtensions Community Group (WECG) 的工作成果，這個 W3C 社群群組的成員是瀏覽器供應商，他們共同制定擴充功能標準。chrome 命名空間不會消失，兩個命名空間都會繼續運作。

決定是否採用瀏覽器命名空間

如果您使用 webextension-polyfill，請先跳到「polyfill 使用者注意事項」，再變更其他項目，因為您的答案不同。

如果您要建構新擴充功能，請將 minimum_chrome_version 設為 "148"，並無條件使用 browser，不必繼續閱讀下方內容。本節的其餘內容適用於現有擴充功能，可協助您決定如何採用。

查看使用者使用的 Chrome 版本

如果您有現有的擴充功能，請先檢查使用者執行的 Chrome 版本，再進行切換。Chrome 會自動更新，但部分使用者會停用更新，其他使用者則使用無法執行最新版本的舊型裝置。請使用自己的數據分析資料確認。如果尚未設定 Analytics，請參閱這篇文章，瞭解如何使用 Google Analytics 4 監控擴充功能的成效。

接著，請選擇路徑：

無條件採用

在資訊清單中設定 minimum_chrome_version，並無條件使用 browser，不需執行階段防護：

{
  "minimum_chrome_version": "148"
}

調高 minimum_chrome_version 時，請使用階段推出功能。如果發生問題，您可以在 Chrome 線上應用程式商店復原擴充功能。

使用執行階段防護機制

在擴充功能的啟動程式碼中，於參照 browser 之前，先加入下列程式碼片段：

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

這會讓 browser 成為舊版中的 chrome 別名，因此程式碼的其餘部分可以無條件使用 browser。

給 Polyfill 使用者的附註

如果擴充功能使用 webextension-polyfill，在 Chrome 148 以上版本中會變成無運算。如果已定義 browser，polyfill 會略過包裝程序，假設主機瀏覽器已提供 API。

先前嘗試在 Chrome 136 中發布命名空間時，因以下原因而遭到復原：由於browser是新定義的，因此 Polyfill 停止包裝，但 Chrome 的 browser.runtime.onMessage尚未支援傳回 Promise 的監聽器，而 Polyfill 一直提供這項功能。依賴該模式的擴充功能會停止運作。Chrome 148 會一併發布命名空間和傳回原生 Promise 的監聽器，避免出現這類間隙。onMessage

使用者群組改用 Chrome 148 後，您就可以移除 Polyfill 依附元件。

其他功能

runtime.sendMessage 中的非同步回應

在 Chrome 148 中，runtime.onMessage 監聽器可以直接傳回 Promise，藉此傳送非同步回應。無論您是使用 chrome.* 或 browser.* 呼叫，這項功能都適用。

先前，如要以非同步方式回應，唯一方法是從監聽器傳回字面值 true，然後稍後呼叫 sendResponse：

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

您現在可以直接傳回 Promise (或使用 async 函式)：

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

return true 模式仍可運作，因此現有程式碼不必變更。