manifest.json 來定義行為、UI、權限與瀏覽器整合。本頁介紹你在瀏覽器擴充功能專案中會看到的副檔名,以及它們各自的歸屬。
如果你想找的是「擴充功能」這個詞所指的 Chrome 或 Firefox 軟體附加元件,請改從什麼是瀏覽器擴充功能? 開始。
JavaScript 副檔名:.js 與 .mjs
瀏覽器擴充功能接受與其他 Web 平台相同的 JavaScript 副檔名:
| 副檔名 | 意義 |
|---|---|
.js | 純 JavaScript。視載入方式而定,可能被當成 ES module 或傳統 script。 |
.mjs | ES module。當你想強制使用 module 語意(尤其是 service worker)時很有用。 |
.cjs | CommonJS。在擴充功能原始碼中很少見;有時會出現在 extension.config.cjs。 |
manifest.json 的 background 區塊包含 "type": "module" 時,背景的 service_worker 會以 module 形式執行。詳見 Manifest V3 疑難排解。
TypeScript 副檔名:.ts 與 .tsx
TypeScript 在 Extension.js 中是一流的原始碼語言:
| 副檔名 | 意義 |
|---|---|
.ts | 不含 JSX 的 TypeScript。 |
.tsx | 含 JSX 的 TypeScript(React、Preact)。 |
.d.ts | 型別宣告檔。不會輸出至建置結果。 |
tsconfig.json。Extension.js 內建合理的預設值。chrome.*、browser.*、import.meta.env 以及公開環境變數的型別來自 @types/chrome 與 Extension.js 自家的環境型別。詳見 TypeScript。
React 副檔名:.jsx 與 .tsx
在瀏覽器擴充功能中使用 React 採用標準的 JSX 副檔名:
| 副檔名 | 意義 |
|---|---|
.jsx | 含 JSX 的 JavaScript。 |
.tsx | 含 JSX 的 TypeScript。 |
瀏覽器擴充功能檔案:manifest.json、背景、content script、頁面
除了 JavaScript 與 TypeScript 原始碼外,擴充功能資料夾通常還包含:
| 檔案或資料夾 | 用途 |
|---|---|
manifest.json | 宣告名稱、版本、權限、進入點與中繼資料。 |
| 背景進入點 | 長時間執行的事件處理。Chromium 上的 Manifest V3 是 service worker。 |
| Content script | 注入符合 URL 條件網頁的程式碼。 |
| 擴充功能頁面 | popup、options、side panel 或 new-tab HTML。 |
| 語系資源 | _locales/<lang>/messages.json 翻譯字串。 |
| 圖示與資產 | 工具列圖示、web-accessible 資源、字型、圖片。 |
.ts、.tsx、.jsx、.vue、.svelte、.css、.less、.scss 與 .module.* 原始碼編譯成上述磁碟結構,並為每個瀏覽器目標產出獨立資料夾(dist/chrome、dist/firefox、dist/edge)。
Extension.js 如何編譯 JavaScript 與 TypeScript 擴充功能
當你執行extension dev 或 extension build 時,Extension.js 會:
- 讀取
manifest.json,找出每個進入點(背景、content script、popup、options、side panel、new-tab、web-accessible HTML)。 - 解析這些進入點所引用的原始檔,包含跨
.ts、.tsx、.jsx、.vue、.svelte與各種樣式類型的 import。 - 透過 Rspack 以擴充功能感知的預設值編譯:在有幫助的地方做 code splitting,在瀏覽器不允許的地方(service worker、content script)則不切分。
- 把結果輸出到
dist/<browser>,並附上專為該目標過濾過的 manifest。
下一步
- 試試
extension create來建立 TypeScript 或 React 擴充功能。 - 閱讀 TypeScript 與 React。
- 閱讀 Manifest V3 疑難排解 以了解 service worker 與 module 規則。
- 使用
extension build建置。