跳轉到主要內容
在你另行宣告之前,擴充功能裡的每個檔案都只屬於你的擴充功能。網頁無法載入它,執行在該頁面裡的 content script 也不行。web_accessible_resources 這個 manifest 鍵就是把特定檔案開放給特定來源的白名單。本頁說明哪些呼叫端需要項目、物件形式如何運作、glob 與執行階段 URL 的行為,以及缺少項目時主控台會印出哪些行。

檔案被讀取的三種方式,以及哪一種需要宣告

來自擴充功能頁面。 popup、options 頁面、side panel 或 devtools 頁面執行在擴充功能來源上。它可以讀取套件裡的任何檔案,完全不涉及 web_accessible_resources 項目。 來自 content script。 腳本本身的程式碼已經在執行,但它引入的資源並不因此被涵蓋。指向 chrome-extension:// URL 的 img 元素、fetch、FontFace 或動態 import() 都是資源載入,因此該檔案必須被列出。 來自頁面自己的程式碼。 頁面 MAIN world 中的任何東西,包括你用 world: "MAIN" 注入的腳本,都屬於網頁程式碼。它需要該檔案被列出,也需要頁面來源落在 matches 之內。 要記住的規則是:瀏覽器依誰去取這個 URL 來判斷,而不是依誰寫了這段程式碼。

Manifest 片段

Manifest V3 接受一個物件陣列。每個物件把一組 resources 與允許讀取它們的 matches 樣式配對:
  • resources 列出相對於擴充功能根目錄的路徑。相對路徑會從存放 manifest.json 的資料夾開始解析。
  • matches 限定哪些頁面來源可以讀取這些檔案。在功能允許的範圍內把它寫得盡量窄。
  • use_dynamic_url 會要求瀏覽器給出一個按工作階段輪換的 URL,讓頁面無法用固定 id 為你的擴充功能建立指紋。請把它當作 Chromium 欄位。
resources 裡允許使用 glob,Extension.js 會原樣保留它們。它不會把 fonts/*.woff2 展開成明確的檔案清單,因此產出的 manifest 與你的原始碼帶著同一個樣式。當你已經知道檔名時,明確列出仍然比較安全。 在正規化過程中,Extension.js 會丟棄沒有 resources 陣列的 Manifest V3 項目,因為瀏覽器無法據此運作。

在執行階段建立 URL

不要手寫 chrome-extension:// URL。向執行階段索取:
像 /images/logo.png 這樣的根絕對路徑是穩定寫法,也是 路徑解析 會為你改寫的形式。在 content script 裡,同樣的呼叫是到達該檔案的唯一正確方式,因為注入的樣式表或元素中的裸 /images/logo.png 會相對於宿主頁面解析。CSS 用一個網頁字型走完了這個情境。 在 Firefox 上這個輔助函式更重要。Firefox 為每次安裝在 moz-extension:// 來源裡產生隨機 UUID,因此你從某個設定檔複製來的 URL 在其他設定檔裡都是錯的。

各瀏覽器差異

在 Safari 上,只啟用擴充功能還不夠。在你授予網站存取權之前,頁面上不會執行 content script,因此根本不會有人來請求這個資源。啟用與授權步驟請見 Safari。 如果你的原始碼是以 browser.* 撰寫,並且要支援早於 148 的 Chromium 瀏覽器(帶有 devtools_page 時為早於 152),請傳入 --polyfill,讓該命名空間在那裡存在。更新的版本原生提供 browser。請見 跨瀏覽器相容。

你會看到的主控台錯誤

把你看到的那一行複製去搜尋。每一行對應一個原因。 Denying load of chrome-extension://<id>/images/logo.png. Resources must be listed in the web_accessible_resources manifest key. 該檔案不在任何 resources 陣列裡,或者請求它的頁面在 matches 之外。加上這個路徑,然後確認樣式涵蓋了該頁面來源。 GET chrome-extension://invalid/ net::ERR_FAILED 同一次拒絕在網路面板中的樣子。Chromium 會把被封鎖的擴充功能 URL 改寫成 chrome-extension://invalid/,因此請求裡看不到 id。要修的是 manifest 項目,而不是這次 fetch。 Security Error: Content at https://example.com/ may not load or link to moz-extension://<uuid>/images/logo.png. 同一個問題在 Firefox 上的形式。附加元件沒有列出該檔案,因此頁面不被允許連結到它。 Failed to load resource: net::ERR_FILE_NOT_FOUND 項目是對的,但產物裡沒有這個檔案。到 dist/<browser>/ 檢查你宣告的那個確切路徑。 Uncaught ReferenceError: browser is not defined 一次 browser.runtime.getURL 呼叫落到了沒有 polyfill 的早於 148 的 Chromium 瀏覽器(帶有 devtools_page 時為早於 152)上。請用 --polyfill 建置,或者改呼叫 chrome.runtime.getURL。

Extension.js 的做法

Extension.js 會把你宣告的內容與建置發現的內容合併,然後為每個目標正規化結果:
  • 當執行階段需要頁面讀取這些資源時,content script 匯入的資源和 content script 的 CSS 產物會被自動加入。字型遵循下面單獨的規則。
  • 從 4.1.41 之後的版本開始,注入的樣式表載入的檔案也會被加入。Chromium 與 Safari 目標列出每一個這樣的檔案。Firefox 目標只列出字型,因為 Firefox 的 Manifest V3 在沒有這個項目時會擋下注入樣式表的字型,而不列出也會載入它的圖片。
  • 從 4.1.41 之後的版本開始,只有當 content script、content script 的樣式表或依檔案注入的樣式表載入某個字型時,Extension.js 才會把它列進 web_accessible_resources。只有擴充功能頁面載入的字型會隨建置產出,但沒有項目。
  • 路徑會為產物正規化。Extension.js 會去掉 public/ 前綴和開頭的斜線,因此項目指向檔案真正落地的位置。
  • glob 保持原樣,帶連接埠或連接埠萬用字元的比對樣式(例如 http://localhost:3000/*)會被接受而不是被拒絕。
  • 如果你寫的某個群組只有 extension_ids 而沒有 matches,產出的 manifest 裡也不會出現 matches。
  • 在開發中,Extension.js 會為項目集合打補丁,讓重新載入與熱模組替換所需的資源保持可達。該補丁僅用於開發。請見 重新載入與 HMR。
  • 從 4.2.0 之後的版本起,已列出的樣式表若以 url() 指向建置不會交付的檔案,會以 W_WAR_INVALID 發出警告並列出每個目標。樣式表照原樣複製,所以瀏覽器會對這些檔案回 404。
  • 從 4.2.0 之後的版本起,已列出的 public 根路徑(例如 /foo.png)沒有對應檔案時,dev 會像建置一樣以 W_ASSET_MISSING 發出警告。之前建置留在輸出資料夾裡的副本不再算數,在 dev 期間刪除的已列出檔案會從輸出中移除並發出警告。

在腳本建構出頁面 URL 之前,頁面保持私有

從 4.1.39 之後的版本起,只有當 content script 建構出某個 HTML 頁面的 URL 時,建置才會把這個頁面加入 web_accessible_resources。把路徑傳給 runtime.getURL 就是這個訊號:
建置能追蹤字面值路徑、保存這個路徑的常數,以及把第一個引數傳給 getURL 的輔助函式。把擴充功能來源或 runtime.id 與路徑串接起來的 URL 也算。 只是提到頁面名稱的腳本不會公開它。常見的情況是:content script 把路徑傳給 background,再由 background 在分頁裡開啟這個頁面。頁面保持私有,建置會為每個頁面印出一則說明:
你自己列在 web_accessible_resources 下的頁面仍然是公開的,也不會為它印出這則說明。 自動合併很方便,但它不是審閱。發布前請讀一遍產出的 dist/<browser>/manifest.json,確認公開出去的集合正是你打算公開的集合:
  • 把 matches 限定在確實需要該檔案的網域上。
  • 優先使用明確的資源清單,而不是寬鬆的 glob。
  • 讓敏感檔案留在白名單之外,改從擴充功能頁面提供它們。
  • 每次新增 content script 匯入、字型或新的靜態資源後,重新審閱這份清單。
建立一個把擴充功能字型載入頁面的專案,這是這個鍵最小的完整範例:

參見