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那一層。
package.json 也沒有 deno.json 的專案。此時包含 manifest.json 的目錄成為專案根目錄。當那份 manifest 位於 src/ 時,src/ 就是根目錄,特殊資料夾(與 dist/)都位於 src/ 之內。
範本範例
special-folders-pages

pages/ 特殊資料夾的運作。
special-folders-scripts

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 預期的預設匯出合約,可確保注入腳本的熱重載安全:
- 匯出一個預設函式。
- 在函式內進行設定。
- 可選擇回傳一個同步的清理函式。
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')。
僅開發期的進入點
名稱中在副檔名之前帶有.dev. 的頁面或腳本是僅開發期的進入點。extension dev 會像編譯該資料夾中其他檔案一樣編譯它。正式建置(extension build、extension start)則會把它排除在外:沒有 HTML,沒有 chunk,產生的 manifest 中也沒有任何地方點名它。
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 停止,訊息如下:
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 鍵載入附屬擴充功能:
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以保護產生的擴充功能輸出。
下一步
- 進一步了解 頁面重新載入與 hot module replacement(HMR)。
- 在 Content scripts 了解掛載合約。
- 瀏覽 Templates 來建立你的下一個擴充功能。

