Manifest.json 編譯與輸出

​

Manifest 能力

​

Extension.js 從哪裡讀取 manifest

• src/manifest.json（存在時優先）
• 專案根目錄的 manifest.json

​

Extension.js 對 manifest 做了什麼

1. 從你的來源檔輸出 manifest 資產。
2. 為目前作用中的瀏覽器目標過濾帶有瀏覽器前綴的鍵。
3. 為擴充功能輸出套用 manifest 覆寫／路徑標準化。
4. 驗證被引用的檔案（HTML／scripts／CSS／圖示／JSON），在缺漏時及早失敗。

​

一份 manifest，多個瀏覽器

• chromium:* 套用到所有 Chromium 家族瀏覽器，chrome:* 與 edge:* 各自只套用到一個瀏覽器
• firefox:*、gecko:*

• chromium:key
• background.firefox:scripts
• background.chromium:service_worker

​

支援的 manifest 欄位

​

權限設計

• 保持 permissions 小巧而刻意。
• 把 host_permissions 限制在功能所允許的最小範圍。
• 在可能的情況下，把非核心能力放到 optional_permissions 或 optional_host_permissions。
• 當 content script 的比對或 background 能力改變時，重新檢視權限範圍。

​

輸出行為

• background.service_worker 變成 background/service_worker.js
• side_panel.default_path 變成 sidebar/index.html
• page_action.default_popup 變成 page_action/index.html，在 Firefox（任何 manifest 版本）與 Chromium MV2 上是工具列彈出視窗旁的獨立頁面。當 page_action 與 action（或 browser_action）指向同一個檔案時，兩個鍵共用 action/index.html。Chromium MV3 沒有 page action 介面，因此建置會帶著警告從該 manifest 移除 page_action，也不會輸出它的頁面。

• content_scripts/content-0.js
• content_scripts/content-0.css

​

Manifest V2 建置會合併 host permissions 並把 CSP 壓平

firefox reads a Manifest V2 content_security_policy as one string, so the sandbox slot has nowhere to go.
The build wrote the extension_pages policy as that string and dropped the sandbox policy from the built manifest. Scope the object form with the chromium: prefix, or declare a Manifest V3 build for this browser.

{
  "manifest_version": 2,
  "permissions": ["storage"],
  "host_permissions": ["https://example.com/*"],
  "content_security_policy": {
    "extension_pages": "script-src 'self'"
  }
}

​

開發行為

• 當 manifest.json 變更時，Extension.js 會重新編譯並觸發擴充功能 hard reload 流程。
• 如果 manifest 進入點結構變更（例如 script 清單改變），Extension.js 可能需要重新啟動開發伺服器。
• 被 manifest 欄位參考的檔案若缺失，編譯會以聚焦在 manifest 的錯誤訊息失敗。

​

變更結果對照表

​

Extension.js 會替你修復什麼

​

舊版路徑警告

• devtools_page/devtools_page.html
• options_ui/page.html
• background/page.html
• browser_action/default_popup.html
• page_action/default_popup.html
• side_panel/default_path.html
• sidebar_action/default_panel.html

​

最佳實務

• 讓 manifest 路徑相對於擴充功能來源／輸出模型，只有在意指擴充功能輸出根目錄時才使用開頭 /。
• 使用帶瀏覽器前綴的鍵，而不是為每個瀏覽器維護不同的 manifest 檔案。
• 刻意管理進入點變更；在 manifest 中新增／移除 script 經常會改變開發期的 reload 語義。
• 在持續整合（CI）中驗證圖示、JSON 資源與 content script 資產，以及早抓出路徑回歸。
• 不要把 manifest.json 放在 public/ 之下。

​

後續步驟

• 在 dev 更新行為中了解更新結果。
• 在權限與 host 權限中設計最小權限存取。
• 了解 Extension.js 如何處理瀏覽器專屬 manifest 欄位。
• 在頁面重新載入與 hot module replacement（HMR）中了解開發更新流程。

​

影片導覽