dist/<browser> 中正確解析。
運作方式
路徑解析在兩個地方執行:- Manifest 編譯流水線:把 manifest 宣告的路徑解析到輸出的資產。
- JS/TS 的 path-resolve plugin:改寫傳入受支援擴充功能 API 的靜態路徑字串(例如
runtime.getURL、tabs.update、scripting.*、action.*、sidePanel.*)。
package.json 的目錄。這就是為什麼 pages/、scripts/ 與 public/ 輸入只會從那個目錄解析,絕不從 src/ 解析,即使是 src/manifest.json 定義了擴充功能也一樣。參見 特殊資料夾 中的根目錄規則。
支援的輸入樣式
Extension.js 會將常見的路徑輸入正規化如下:pages/ 與 scripts/ 的副檔名對應包含:
.ts、.tsx、.js、.jsx→.js.njk、.nunjucks、.html→.html.scss、.sass、.less、.css→.css
Extension.js 不會改寫的情況
為了避免誤判,Extension.js 會刻意略過下列輸入:http://與https://URLdata:URLchrome://URLmoz-extension://URL- Glob 樣式(
*、?、{}、[]) - 建置無法安全解析的非靜態/動態運算式
Manifest 輸出範例
假設目標瀏覽器為chrome:
並非每個 manifest 欄位都會對應到同名的資料夾。Extension.js 會根據面向瀏覽器的擴充功能合約來決定輸出路徑,而不是你原本的撰寫路徑。
Extension.js 會把所有編譯後的輸出寫入
dist/<browser>。
你的程式碼依路徑指明的頁面
從 4.1.41 之後的版本開始,如果擴充功能裡的腳本把某個頁面撰寫時的路徑當作字串保存,建置會讓這個路徑繼續可用。只回應sender.url 以 /ui/popup/index.html 結尾的背景,或是比較 location.pathname 的頁面,在建置輸出中的表現與在來源資料夾中一致。
- 編譯後的頁面同時發布在
action/index.html和ui/popup/index.html。 - 建置出的 manifest 在
ui/popup/index.html開啟它。 - 建置會印出一行,指出該頁面以及保存這個字串的檔案。
background.page 一律發布為 background/index.html。
從 4.1.41 之後的版本開始,如果指令碼用 getURL 指明了 pages/ 裡的某個頁面(例如 pages/welcome/index.html),編譯後的頁面也會在這個路徑上提供。它的來源檔案不會被複製。
被移動的頁面裡設定的相對路徑
manifest 宣告的每個頁面都會輸出到以它的介面命名的資料夾裡。寫成index.html 的側邊面板會輸出為 sidebar/index.html。建置會改寫頁面 HTML 裡的路徑。頁面的腳本設定的相對 src 或 href 不會被改寫,瀏覽器會相對於新資料夾解析這個路徑:
/ 開頭,它就會從擴充功能根目錄解析。從 4.1.39 之後的版本起,如果檔案只存在於原本的相對位置,建置會印出一則 Runtime-risk 警告。警告會寫明頁面、頁面請求的路徑、輸出裡實際的路徑,以及應該寫的路徑。
引用輸出檔案
像chrome.runtime.getURL() 這類瀏覽器 API,請優先使用穩定的輸出根目錄路徑:
chrome-extension:<extension-id>/icons/icon.png
診斷與安全檢查
當解析器無法把引用的路徑對應到封裝後的資產時,會發出警告(例如嵌套的src/pages/...,或改寫後 public/ 檔案缺失)。Extension.js 會在每次檔案轉換時對警告進行去重,以減少噪音。
重要路徑規則
- 開頭的
/代表擴充功能輸出根目錄,而不是檔案系統根目錄。 public/...與/public/...會正規化為輸出根目錄的資產。pages/與scripts/是擁有副檔名對應規則的特殊資料夾。- Extension.js 會保留作業系統的絕對檔案路徑,而不把它們當成擴充功能輸出路徑。
- 當無法安全判定最終封裝路徑時,Extension.js 會略過動態運算式。
最佳實務
- 把
pages/、scripts/與public/放在專案根目錄,路徑改寫才能可預期。 - 擴充功能 API 路徑盡量使用靜態字串;Extension.js 可能會略過動態運算式。
- 把
/public/...視為輸出根目錄的資產,避免在執行階段做相對於原始碼的假設。 - 在
dev期間留意警告,它們通常代表打包前就有路徑不符。
下一步
- 進一步了解 特殊資料夾。
- 進一步了解 web-accessible resources。

