> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Manifest.json 編譯與輸出

> 把 manifest.json 當作進入點與資產的唯一來源。Extension.js 會編譯、改寫路徑，並產生瀏覽器可直接載入的 manifest。

把 `manifest.json` 視為進入點、資產與瀏覽器專屬行為的唯一來源，讓擴充功能建置維持可預期。

Extension.js 會編譯你的 manifest，過濾帶有瀏覽器前綴的欄位。它會改寫執行階段路徑、驗證被引用的檔案，並為每個目標瀏覽器產出可直接載入的 manifest。

## Manifest 能力

| 能力        | 你會獲得的成果                                   |
| --------- | ----------------------------------------- |
| 瀏覽器專屬欄位過濾 | 保留一份 manifest，同時輸出針對目標瀏覽器的版本              |
| 路徑標準化     | 自動解析執行階段安全的輸出路徑                           |
| 參考驗證      | 在缺少 HTML／script／CSS／JSON／圖示檔案時及早失敗        |
| 針對目標的輸出   | 為每個瀏覽器目標在 `dist/<browser>` 產生 manifest 產物 |

## Extension.js 從哪裡讀取 manifest

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

Extension.js 不會使用 `public/manifest.json` 作為來源 manifest。

當專案有 `package.json` 時，Extension.js 會忽略 `public/manifest.json`。這可避免被複製的靜態資產覆蓋 Extension.js 產生的 manifest。

## Extension.js 對 manifest 做了什麼

在 dev／build 期間，manifest 管線會：

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

## 一份 manifest，多個瀏覽器

帶有瀏覽器前綴的鍵讓你能維持一份 manifest，同時針對瀏覽器專屬行為：

* `chromium:*`、`chrome:*`、`edge:*`
* `firefox:*`、`gecko:*`

這些前綴可套用在最上層的鍵與巢狀 manifest 欄位上。

範例：

* `chromium:key`
* `background.firefox:scripts`
* `background.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 能力改變時，重新檢視權限範圍。

關於權限策略，請參考[權限與 host 權限](/docs/implementation-guide/permissions-and-host-permissions)。

## 輸出行為

Extension.js 在需要時會把 manifest 路徑改寫為可預期的輸出位置。兩個重要範例：

* `background.service_worker` 變成 `background/service_worker.js`
* `side_panel.default_path` 變成 `sidebar/index.html`

Extension.js 也會依 manifest 進入點索引標準化 content script：

* `content_scripts/content-0.js`
* `content_scripts/content-0.css`

這些被輸出的路徑就是瀏覽器實際載入的路徑。撰寫時使用來源路徑，然後讓 Extension.js 為輸出改寫它們。

## 開發行為

* 當 `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 更新行為](/docs/workflows/dev-update-behavior)中了解更新結果。
* 在[權限與 host 權限](/docs/implementation-guide/permissions-and-host-permissions)中設計最小權限存取。
* 了解 Extension.js 如何處理[瀏覽器專屬 manifest 欄位](/docs/features/browser-specific-fields)。
* 在[頁面重新載入與 hot module replacement（HMR）](/docs/features/reload-and-hmr)中了解開發更新流程。