manifest.json 中的圖示路徑、解析 public/相對路徑、輸出圖示資產,並在開發期間監看圖示檔案。
範本範例
action

manifest.json 中宣告工具列圖示的 action 擴充功能。
圖示能力
支援的圖示欄位
Chromium 不接受
.svg(或 .webp)作為 icons 與 action 圖示。把這些欄位指向
SVG 的 manifest 能在 Firefox 中載入,但在 Chrome、Edge、Brave 與 Opera 中會失敗。
針對所有 Chromium 目標請提供 PNG 檔案。sidebar_action 與
browser_action.theme_icons 是 Firefox 欄位,而且 sidebar_action.default_icon
對 .svg 的支援在那裡也只是部分的(*)。在 manifest.json 中宣告圖示的範例
圖示變體
icon_variants 為每種配色方案宣告一組圖示。Extension.js 會讀取頂層的這個鍵,以及 action、browser_action 與 page_action 之下的這個鍵。
icons 一樣被輸出與檢查:
- 每個變體檔案都輸出在它的原始位置,它在 manifest 中的路徑遵循與
icons相同的規則。 - 缺少變體檔案時,建置會以圖示錯誤停止,錯誤裡會寫出這個鍵:
Can't find an icon file listed in icon_variants.
ExtensionIconVariants 旗標時才會讀取 icon_variants,Firefox 目前還不讀取這個鍵。對於這些目標,建置會保留你的 manifest 中宣告的 icons 與 action 的 default_icon。
如果 manifest 中沒有它們,建置會先用不帶 color_schemes 的變體群組來填入,其次用淺色群組。Chromium 只接受 PNG 尺寸,Firefox 還可以使用 any 的 SVG。
Safari 會在工具列上讀取 icon_variants,寫在頂層或 action 下都可以,並且優先於 icons。在 Safari 27 上實測,它一律繪製淺色組,在深色外觀下也不會切換到深色組。Apple 的應用程式轉換器不讀取這個鍵,只用 icons 來產生應用程式圖示。所以 Safari 建置會得到同樣的後備處理:
- 如果 manifest 中有
icons與 action 的default_icon,建置會保留它們。 - 如果 manifest 中沒有它們,建置會先用不帶
color_schemes的變體群組來填入,其次用淺色群組。 - 建置優先使用 PNG 尺寸,只有在沒有任何群組提供 PNG 時才使用 SVG。
icon_variants本身會留在 Safari 的輸出裡,所以 Apple 的轉換器仍然會把這個鍵列為不支援。
icons 時,提示也會說明:
chromium:icon_variants 或 firefox:icon_variants 底下的清單只會在對應瀏覽器的建置中輸出它的檔案。請見瀏覽器專屬的 manifest 欄位。
從 SVG 產生各尺寸 PNG
把 SVG 保留為設計原始檔,匯出所有瀏覽器都接受的 PNG 尺寸。下面這條命令使用 librsvg 提供的rsvg-convert(macOS 上 brew install librsvg,Debian 與 Ubuntu 上 apt install librsvg2-bin):
icons 與 action.default_icon 指向這些 PNG 檔案。
輸出路徑
典型的圖示輸出:icons/ 資料夾。宣告為 images/icon.png 的圖示會輸出在
images/icon.png,而輸出的 manifest 也仍然指向同一個路徑。
路徑行為
- Extension.js 從 manifest 資料夾解析相對的圖示路徑。
- 開頭為
/與public/...的路徑會以擴充功能 public 根目錄的語義來解析。 - Extension.js 可以監看 public 資料夾中的資產,而不必透過圖示功能本身重新輸出。
- 由動態匯入的模組設定的圖示,會發布在載入該模組的 worker 或頁面旁邊。見執行階段載入的檔案。
開發行為
- 變更現有圖示檔案會觸發重新編譯。
- 當 manifest 的修改變更了圖示參考時,正在執行的
extension dev工作階段會自行重新啟動編譯器。 - 缺少必要的圖示檔會造成建置錯誤(某些可選的圖示群組會改為警告)。
最佳實務
- 明確宣告 manifest 中的圖示欄位,而不是仰賴附帶的資產 import。
- 提供多種圖示尺寸(
16、32、48、128),讓瀏覽器各介面顯示更銳利。 - 保持圖示檔名穩定,以減少開發期 manifest 的變動。
- 刻意使用 public 根路徑,並測試最終 manifest 的輸出路徑。
後續步驟
- 繼續閱讀 web-accessible resources。
- 進一步了解 Special folders。

