跳轉到主要內容
當擴充功能需要無法乾淨放入 manifest.json 的 entrypoint 或資產時,使用特殊資料夾。 處理額外頁面、執行階段注入的腳本、需要精確路徑的靜態資產,以及本機開發用的附屬擴充功能,而不破壞專案結構。

特殊資料夾的位置

特殊資料夾只會從專案根目錄解析,別無其他位置。規則如下:
  • 專案根目錄是包含 package.json(或 deno.json)的目錄。
  • 把 pages/、scripts/、public/ 與 extensions/ 放在那個目錄,也就是 package.json 旁邊。
  • src/scripts/ 不是特殊資料夾。Extension.js 會忽略巢狀的特殊資料夾副本,因此那裡的檔案永遠不會成為 entrypoint 或被複製的資產。
  • 把 manifest.json 移進 src/ 不會移動專案根目錄。骨架範本出貨時就是 src/manifest.json 加上高一層的 package.json,而特殊資料夾屬於 package.json 那一層。
唯一以 src 為根的例外:一個既沒有 package.json 也沒有 deno.json 的專案。此時包含 manifest.json 的目錄成為專案根目錄。當那份 manifest 位於 src/ 時,src/ 就是根目錄,特殊資料夾(與 dist/)都位於 src/ 之內。
我的 scripts/ 資料夾沒有出現在 dist/。 這幾乎都對應到上面的規則: 資料夾位在 src/ 底下,而不是 package.json 旁邊。把它移到專案根目錄。 如果它已經在那裡,確認該檔案不是 Node.js 輔助腳本,建置會把這類檔案排除在外。

範本範例

special-folders-pages

special-folders-pages template screenshot 透過額外的 HTML entrypoint,實際看看 pages/ 特殊資料夾的運作。
儲存庫:extension-js/templates/special-folders-pages

special-folders-scripts

special-folders-scripts template screenshot 透過獨立的腳本 entrypoint,實際看看 scripts/ 特殊資料夾的運作。
儲存庫:extension-js/templates/special-folders-scripts

為什麼這很重要

manifest 並未直接宣告許多擴充功能檔案,包括 iframe 頁面、你以 chrome.scripting.executeScript 動態注入的腳本,以及靜態廠商資產。你在開發階段可能也需要附屬擴充功能。特殊資料夾讓這些都成為建置流水線中的一等公民。

運作方式

每個特殊資料夾都有特定角色:

pages/:額外的 HTML entrypoint

pages/ 用來放置額外的擴充功能頁面,例如 sandbox iframe、診斷頁面或內部工具。 Extension.js 會把 pages/ 中的每個 .html 視為 entrypoint,並像 manifest 宣告的頁面一樣編譯。 從 4.1.41 之後的版本開始,如果指令碼用 getURL 指明了 pages/ 裡的某個頁面(例如 pages/welcome/index.html),編譯後的頁面也會在這個路徑上提供。它的來源檔案不會被複製。 關於 sandbox iframe 範例,請參考 Chrome Sandbox Sample。

scripts/:獨立的腳本 entrypoint

scripts/ 用來放置動態載入、不綁定特定 HTML 頁面 entry 的可執行腳本。 Extension.js 會把 scripts/ 中的檔案編譯為 entrypoint,並使用與專案其他部分相同的副檔名解析流程。

根目錄位置與輸出路徑

大多數 scripts/ 設定問題都出在這兩點。 位置。scripts/ 放在 package.json(或 deno.json)旁邊,也就是專案根目錄,而不是 src/ 裡。即使 manifest.json 位於 src/,這條規則仍然成立。唯一的例外是既沒有 package.json 也沒有 deno.json 的專案,此時 manifest 所在目錄就是根目錄。請見特殊資料夾的位置。 **輸出路徑。**注入編譯後的檔案。scripts/foo.ts 原始檔會被編譯為 scripts/foo.js,所以 chrome.scripting.executeScript({ files }) 與 chrome.scripting.registerContentScripts({ js }) 必須寫 .js 檔案。寫 .ts 路徑時建置正常,但在瀏覽器裡會 404。Extension.js 會在建置時對編譯原始路徑字面值發出警告,並指出應使用的輸出路徑。
background.ts
在擴充功能頁面裡,路徑要從根目錄開始寫,例如 /scripts/foo.js。Firefox 會相對於頁面解析開頭沒有斜線的路徑。要讓這個檔案在頁面自己的 world 中執行,請見在執行階段注入腳本。

資料夾合約

你放進 scripts/ 或 pages/ 的每個檔案都會輸出到一個可預測的路徑。scripts/foo.ts 會變成 dist/<browser>/scripts/foo.js,pages/extra.html 會變成 dist/<browser>/pages/extra.html。不需要在任何地方宣告該檔案。像 chrome.runtime.getURL("pages/extra.html") 或 chrome.scripting.executeScript({ files: ["scripts/foo.js"] }) 這樣的執行階段字串都能找到它。沒有任何地方引用的檔案同樣會被輸出,建置也不會為此印出警告。建置會把 Node.js 輔助腳本排除在外:帶有 shebang、含有 Node.js import,或是路徑被某個 package.json script 執行的檔案。要關閉某個資料夾,在 extension.config.js 中把它的鍵設為 false:
extension.config.js
完整的 folders 鍵請參閱特殊資料夾的位置。 從 4.2.0 之後的版本起,建置只在 pages/ 與 scripts/ 中尋找入口,任意深度,並略過 node_modules 資料夾。頁面以 .html 結尾。腳本以 .js、.mjs、.jsx、.mjsx、.ts、.mts、.tsx 或 .mtsx 結尾,並且必須是小寫,所以 scripts/Foo.JS 不是入口。兩個資料夾裡的連結只要仍在專案之內就會被跟隨。pages/ 或 scripts/ 裡建置無法讀取的資料夾會讓建置以 E_FOLDER_UNREADABLE 停止,訊息會指名那個資料夾。 從 4.2.0 之後的版本起,這兩個資料夾也必須以小寫命名。任何建置在任何磁碟上都不會讀取 Pages/ 或 Scripts/ 資料夾,因此同一個專案在 macOS、Windows 與 Linux 上的建置結果相同。每個這樣的資料夾都會印出一則 W_PROJECT_LAYOUT 警告,指名該資料夾並請你重新命名。 從 4.2.0 之後的版本起,scripts/ 中的宣告檔(.d.ts、.d.mts 或 .d.cts)永遠不是入口。

兩個檔案對應同一個入口名稱

入口以它在資料夾內的路徑去掉副檔名來命名。子資料夾裡名為 index.html 的頁面代表該子資料夾。所以 pages/a.html 與 pages/a/index.html 都佔用 pages/a 這個名稱,scripts/a.js 與 scripts/a.ts 都佔用 scripts/a。 從 4.2.0 之後的版本起,建置使用路徑排序最後的檔案:pages/a/index.html 優先於 pages/a.html,scripts/a.ts 優先於 scripts/a.js。透過資料夾內的連結到達的檔案遵循同樣的規則。一則 W_PROJECT_LAYOUT 警告會指名每個入口名稱、被使用的檔案以及每個被忽略的檔案。請重新命名或刪除被忽略的檔案。

scripts/ 裡的輔助模組

scripts/ 裡的每個檔案都會被建置成一個獨立的 entry。被其他檔案匯入的輔助模組會多輸出一個沒有任何東西載入的檔案。從 4.1.39 之後的版本起,如果一個檔案被其他檔案匯入,又沒有任何地方依輸出路徑提到它,建置會為它印出一則警告。警告裡給出可以直接貼上的 exclude 值:
extension.config.js
加上這個鍵之後,這個檔案不再輸出,警告也隨之消失。你的程式碼依輸出路徑提到的檔案不會觸發警告,因為那是一個被注入的腳本。

重要合約

當你用 scripts/ entry 作為類似 content script 的執行階段 entry 時,請遵循 content script 初始化模式。這是 Extension.js 預期的預設匯出合約,可確保注入腳本的熱重載安全:
  • 匯出一個預設函式。
  • 在函式內進行設定。
  • 可選擇回傳一個同步的清理函式。
這在開發階段最重要,Extension.js 會安全地重新掛載類 content script 的 entry,而不是進行完整的頁面重載。

scripts/ 不允許 Node.js 腳本

Extension.js 會把 scripts/ 內的每個檔案以瀏覽器 content-script 掛載 runtime 包起來。如果你把 Node.js 專用檔案(例如 CLI 啟動器或建置輔助工具)放在這裡,包裝會破壞檔案。 shebang 不再位於第 1 行,且瀏覽器情境中無法使用僅限 Node 的 API。 Extension.js 會偵測兩種 Node.js 指標,並把該檔案排除在建置之外:
  • 第 1 行的 shebang(#!/usr/bin/env node)。
  • 來自 node: 協定的 import(例如 import fs from 'node:fs')。
如果你看到 scripts/ is a reserved folder in Extension.js,請把檔案移到專案 根目錄下的其他資料夾,例如 bin/、tools/、ops/、tasks/ 或 ci-scripts/。
關於動態注入範例,請參考 Chrome Scripting Sample。

僅開發期的進入點

名稱中在副檔名之前帶有 .dev. 的頁面或腳本是僅開發期的進入點。extension dev 會像編譯該資料夾中其他檔案一樣編譯它。正式建置(extension build、extension start)則會把它排除在外:沒有 HTML,沒有 chunk,產生的 manifest 中也沒有任何地方點名它。
把它用於測試用的 harness 頁面、模型一致性 bench,或只有開發者才會執行的腳本。harness 頁面可以在擴充功能的 overlay 底下播放本機影片。開發期間該檔案保留其所在資料夾的輸出路徑,因此 chrome.runtime.getURL("pages/player.dev.html") 找得到它。這個頁面不在正式輸出中,所以在會發佈的程式碼裡請為這個參照加上防護,例如放在 process.env.NODE_ENV !== "production" 之後。
  • 這個慣例只看檔名。名為 dev/ 的資料夾只是一般資料夾,pages/dev/player.html 會發佈。
  • extension build --mode development 是開發期編譯,所以會保留這些進入點。
  • 不是進入點的檔案,例如某個頁面 import 的 player.dev.css,跟隨 import 它的頁面。
  • 要依模式或環境把額外檔案複製進建置,見 extension.config.js 中的 include。

public/:僅複製的靜態資產

當你需要穩定的檔案路徑且不需打包/轉換時,使用 public/。 Extension.js 會把 public/ 下的所有內容 1:1 複製到輸出根目錄。 從 4.1.39 之後的版本起,這次複製在每種模式下都是逐位元組的。正式建置不會壓縮或轉換 public/ 下的檔案。第三方腳本會保留它的授權標頭註解、最後一個運算式,以及 sourceMappingURL 註解。你在 extension.config.js 的 include 下宣告的檔案也以同樣的方式產出,腳本除外。除非你選擇關閉,正式建置會壓縮 include 進來的腳本,見建置中的額外檔案。

重要的 public/ 防護

不要把 manifest.json 放在 public/manifest.json。Extension.js 會阻擋這種情況,避免在編譯時覆蓋產生的 manifest。 建置會停止。從 4.2.0 之後的版本起,建置會以 E_MANIFEST_IN_PUBLIC 停止,訊息如下:
從 4.2.0 之後的版本起,某個入口已經寫入其輸出路徑的 public/ 檔案不會被複製。入口的檔案勝出,一則 W_PROJECT_LAYOUT 警告會指名該檔案。

資料夾名稱必須小寫

從 4.2.0 之後的版本起,public 資料夾必須命名為小寫的 public/。Public/ 或 PUBLIC/ 資料夾會印出一則 W_PROJECT_LAYOUT 警告,請你重新命名:
  • 在不區分大小寫的磁碟上(macOS 的預設設定),這個資料夾仍會發布。
  • 此時警告會說明,其他拼寫會在下一個主要版本中失效。
  • 在區分大小寫的磁碟上(大多數 Linux 系統如此),這個資料夾裡的內容都不會發布。
  • 與真正的 public/ 資料夾並排的 PUBLIC/ 資料夾是第二個資料夾。它裡面的內容在任何磁碟上都不會發布,警告也會這樣說明。

永遠不會打包的檔案

從 4.1.41 之後的版本起,私有檔案永遠不會進入建置,即使它們位於 public/ 中。這包括 .env、.npmrc、.git 與 .DS_Store 等檔案。引用這類檔案的頁面或樣式表 url() 會警告一次,說明該檔案未被打包。警告帶有同類缺少檔案所用的代碼。請把內容移到另一個名稱的檔案中。 從 4.1.41 之後的版本起,dev 也不會提供這些檔案。這包括 env 檔案、Thumbs.db 與 desktop.ini 等作業系統中繼資料、儲存庫檔案,以及 name~ 等編輯器備份。請求這類檔案會像缺少檔案一樣回傳 404,編輯它們也不會重新載入擴充功能。

extensions/:附屬擴充功能(僅載入)

當你使用附屬擴充功能(例如 DevTools 輔助工具)時,Extension.js 在 dev/preview/start 流程中支援 extensions/ 資料夾作為僅載入來源。 整體而言:
  • 掃描 extensions/ 下含有 manifest.json 的子資料夾作為解壓後的擴充功能根目錄。
  • 以瀏覽器命名的子資料夾只會為該瀏覽器家族載入:extensions/chrome/ 用於 Chromium 目標,extensions/edge/ 用於 Edge,extensions/firefox/ 用於 Gecko 目標。根層子資料夾與你明確設定的項目在所有瀏覽器上都會載入。
  • Extension.js 會將附屬擴充功能與主要擴充功能一起載入。
  • 此資料夾用於載入附屬擴充功能,而非把它們建置進主產物。
你也可以透過 --extensions CLI 旗標或 extension.config.js 中的 extensions 鍵載入附屬擴充功能:
Extension.js 會自動下載、解壓並把商店 URL 與你的擴充功能一起載入。 可接受的商店連結有 chromewebstore.google.com(以及舊的 chrome.google.com/webstore 形式)、microsoftedge.microsoft.com 與 addons.mozilla.org,有沒有協定或 www. 前綴都可以。下載的商店擴充功能會落在 extensions/<browser>/ 下,而且只為該瀏覽器載入。來自其他主機的連結、單獨的商店 id,或既不是連結也不是路徑的項目會被回報為錯誤,而不是被默默丟棄。 從 4.1.41 之後的版本起,有些搭配擴充功能條目只會以 W_COMPANION_EXTENSION_PATH 警告。這涵蓋專案之外的條目、不是未封裝擴充功能的資料夾,以及不存在的資料夾。瀏覽器會在沒有它的情況下開啟。唯一 manifest 屬於 extensions/ 底下某個搭配擴充功能的專案,仍會以 E_COMPANION_EXTENSION_PATH 遭到拒絕。

開發行為(監看模式)

在開發監看模式下,Extension.js 會監控 pages/ 與 scripts/ 的檔案集合變更。 在 pages/ 或 scripts/ 下新增檔案,會讓編譯器自行重新啟動。從 4.1.41 之後的版本開始,在那裡刪除或重新命名檔案也會這樣,而且重新啟動會移除已不存在的檔案的輸出。不需要手動重新啟動。

最佳實務

  • 共用執行階段資產放在 public/:用在必須保持名稱與路徑精確的檔案。
  • pages/ 與 scripts/ 用於真正的 entrypoint:讓 manifest 之外的執行路徑保持明確。
  • 附屬擴充功能保持獨立:把 extensions/ 視為本地工作流程的僅載入相依。
  • public/ 中不要放 manifest.json:Extension.js 會阻擋 public/manifest.json 以保護產生的擴充功能輸出。

下一步

模板示範