manifest.json 視為進入點、資產與瀏覽器專屬行為的唯一來源，讓擴充功能建置維持可預期。
Extension.js 會編譯你的 manifest，過濾帶有瀏覽器前綴的欄位。它會改寫執行階段路徑、驗證被引用的檔案，並為每個目標瀏覽器產出可直接載入的 manifest。
Manifest 能力
| 能力 | 你會獲得的成果 |
|---|---|
| 瀏覽器專屬欄位過濾 | 保留一份 manifest，同時輸出針對目標瀏覽器的版本 |
| 路徑標準化 | 自動解析執行階段安全的輸出路徑 |
| 參考驗證 | 在缺少 HTML／script／CSS／JSON／圖示檔案時及早失敗 |
| 針對目標的輸出 | 為每個瀏覽器目標在 dist/<browser> 產生 manifest 產物 |
Extension.js 從哪裡讀取 manifest
src/manifest.json（存在時優先）- 專案根目錄的
manifest.json
public/manifest.json 作為來源 manifest。
當專案有 package.json 時，Extension.js 會忽略 public/manifest.json。這可避免被複製的靜態資產覆蓋 Extension.js 產生的 manifest。
Extension.js 對 manifest 做了什麼
在 dev／build 期間，manifest 管線會：- 從你的來源檔輸出 manifest 資產。
- 為目前作用中的瀏覽器目標過濾帶有瀏覽器前綴的鍵。
- 為擴充功能輸出套用 manifest 覆寫／路徑標準化。
- 驗證被引用的檔案（HTML／scripts／CSS／圖示／JSON），在缺漏時及早失敗。
一份 manifest，多個瀏覽器
帶有瀏覽器前綴的鍵讓你能維持一份 manifest，同時針對瀏覽器專屬行為：chromium:*、chrome:*、edge:*firefox:*、gecko:*
chromium:keybackground.firefox:scriptsbackground.chromium:service_worker
支援的 manifest 欄位
常見的進入點相關欄位包含：| Manifest 欄位 | 預期檔案類型 |
|---|---|
action.default_popup | .html |
background.page | .html |
background.service_worker | .js, .jsx, .ts, .tsx, .mjs |
browser_action.default_popup | .html |
chrome_url_overrides.bookmarks | .html |
chrome_url_overrides.history | .html |
chrome_url_overrides.newtab | .html |
content_scripts.js | .js, .jsx, .ts, .tsx, .mjs |
content_scripts.css | .css, .scss, .sass, .less |
declarative_net_request.rule_resources | .json |
devtools_page | .html |
icons | .png, .jpg 與其他影像格式 |
options_ui.page | .html |
options_page | .html |
page_action.default_popup | .html |
sandbox.pages | .html |
side_panel.default_path | .html |
sidebar_action.default_panel | .html |
storage.managed_schema | .json |
theme_icons | .png, .jpg 與其他影像格式 |
user_scripts.api_script | .js, .jsx, .ts, .tsx, .mjs |
web_accessible_resources | .png, .jpg, .css, .js |
權限設計
Manifest 也是你擴充功能宣告自身能力的地方。Extension.js 會編譯 manifest，但你仍需要良好的權限設計。- 保持
permissions小巧而刻意。 - 把
host_permissions限制在功能所允許的最小範圍。 - 在可能的情況下，把非核心能力放到
optional_permissions或optional_host_permissions。 - 當 content script 的比對或 background 能力改變時，重新檢視權限範圍。
輸出行為
Extension.js 在需要時會把 manifest 路徑改寫為可預期的輸出位置。兩個重要範例：background.service_worker變成background/service_worker.jsside_panel.default_path變成sidebar/index.html
content_scripts/content-0.jscontent_scripts/content-0.css
開發行為
- 當
manifest.json變更時，Extension.js 會重新編譯並觸發擴充功能 hard reload 流程。 - 如果 manifest 進入點結構變更（例如 script 清單改變），Extension.js 可能需要重新啟動開發伺服器。
- 被 manifest 欄位參考的檔案若缺失，編譯會以聚焦在 manifest 的錯誤訊息失敗。
變更結果對照表
| Manifest 變更類型 | 典型結果 |
|---|---|
| 更新非結構性的值（例如描述／權限中繼資料） | Hard reload 流程 |
| 更新仍可正確解析的資產路徑值 | 重新編譯 + hard reload 流程 |
| 在 manifest 中新增／移除 script 或頁面進入點 | 需要重新啟動 |
| 引入無效或缺失的被引用檔案 | 建置錯誤（先修正再重跑） |
最佳實務
- 讓 manifest 路徑相對於擴充功能來源／輸出模型，只有在意指擴充功能輸出根目錄時才使用開頭
/。 - 使用帶瀏覽器前綴的鍵，而不是為每個瀏覽器維護不同的 manifest 檔案。
- 刻意管理進入點變更；在 manifest 中新增／移除 script 經常會改變開發期的 reload 語義。
- 在持續整合（CI）中驗證圖示、JSON 資源與 content script 資產，以及早抓出路徑回歸。
- 不要把
manifest.json放在public/之下。
後續步驟
- 在 dev 更新行為中了解更新結果。
- 在權限與 host 權限中設計最小權限存取。
- 了解 Extension.js 如何處理瀏覽器專屬 manifest 欄位。
- 在頁面重新載入與 hot module replacement（HMR）中了解開發更新流程。