範本範例
content-sass

content-custom-font

CSS 能力
在哪裡參考 CSS
manifest.json(content_scripts[].css)- HTML 檔案(
<link rel="stylesheet" href="...">) - Script 中的 import(
import "./styles.css",啟用時也包含 Sass/Less)。在 content script 裡,這種 import 本身不會替任何東西加上樣式。
CSS 支援
Manifest 中的 CSS 進入點:範例:manifest.json 中的 CSS
範例:在擴充功能頁面 script 中引用 CSS
content script 中的樣式
在 content script 裡,單純的import "./styles.css" 得到的值是一個 data: URL 形式的樣式表。它本身不會替任何東西加上樣式。Sass 與 Less 的 import 也是一樣。
Extension.js 只在一種情況下替你放置這份樣式表。這條 import 必須寫在已宣告的 content script 的入口檔裡,而且腳本必須用 data-extension-root 標記一個宿主元素。樣式表隨後會進入這個宿主的 shadow root。請見 Shadow DOM。
要替頁面本身加上樣式,請使用下列任一種方式:
最後一種方式會讀取 import 得到的值,再自己放置它:
scripts/ 檔案不會得到任何自動放置。在那裡請讀取這個值,再把它設到 <link> 上。
從 4.1.39 之後的版本起,如果一條只為副作用而寫的樣式 import 沒有被任何東西放置,建置會印出一則警告。
樣式政策嚴格的頁面
頁面的內容安全政策(CSP)也決定 content script 自己的 DOM 呼叫能做什麼。結果取決於腳本執行在哪個 world。在送出style-src 'self' 的頁面上:
這些結果是在 Chrome 151 與 Firefox 160 上量測的,
dev 與正式建置都一樣。shadow root 裡的 <style> 元素會和文件裡的一樣被拒絕。
在送出 default-src 'self' 的頁面上,fetch(href) 也會被拒絕。在 MAIN world 裡兩個瀏覽器都是如此,在 isolated world 裡只有 Firefox 如此。
建置看不到腳本將要造訪的頁面的政策。它不會更動這些呼叫,也不會印出警告。必須在這種政策下運作的 MAIN world 腳本,可以不發請求,直接從 URL 裡讀出樣式表並採用它:
@import,以及 public/ 裡被注入的樣式表,見執行階段載入的檔案。
內容腳本中的網頁字型
把介面渲染到 shadow root 的內容腳本,無法只靠 CSS 載入網頁字型。有兩條平台規則會擋住它,而且都是靜默的。 shadow root 內部的@font-face 永遠不會生效。 字型(font face)解析的是文件的字型集,而不是 shadow 樹,所以 Chrome 會忽略該規則並靜默回退。修正前在 content-custom-font 範本上實測:document.fonts 為空,沒有發出任何字型請求,以 "Momo Signature", cursive 排版的文字寬度與純 cursive 完全相同。
注入樣式表中的根絕對 url() 會相對宿主頁面解析。 注入到 example.com 的樣式表中的 url(/fonts/Momo.woff2) 請求的是 https://example.com/fonts/Momo.woff2,而不是擴充功能自己的那份檔案。
改為把字型註冊到頁面自身的字型集上,URL 指向擴充功能,並在內容腳本卸載時移除它:
web_accessible_resources 中宣告:
document.fonts,shadow 樹就可以在一般的 font-family 規則裡以名稱使用它。可運行的版本見 content-custom-font。
以 URL 匯入樣式表
從 4.1.41 之後的版本起,在 content script 之外,?url 匯入會給出編譯後樣式表的 URL:
assets/ 下。該樣式表中相對的 url() 或 @import 無法跟著它到新位置,一則警告會列出這些位址。把那些檔案移到 public/ 中並從根路徑引用,或不帶 ?url 匯入該樣式表。
依情境的輸出行為
Extension.js 會依照哪一個進入點 import 該 CSS 自動拆分情境。
從 4.1.41 之後的版本起,content script 樣式表會連同它匯入的每個專案
.css 檔案的規則一起發布。匯入的 media、supports 或 layer 條件會被保留。content script 樣式表從 data: URL 載入,瀏覽器在那裡不會擷取任何相對匯入。套件與遠端的匯入保持原樣。專案之外的樣式表或私有檔案不會被帶進來,建置會點名該檔案發出警告。在所有工具執行完之後仍留在樣式表中的 @import,會警告它的規則不會載入。
從 4.1.41 之後的版本起,Extension.js 以自己的規則編譯每個樣式表,這些規則優先於你的設定。你的設定為 .css、.scss、.sass 或 .less 檔案設定的 type 不會套用。一則警告會說明這一點。請從該規則中移除 type。要取得檔案 URL,以 ?url 匯入樣式表。要取得文字,以 ?raw 匯入。
正式建置壓縮樣式表時,Extension.js 會把結果與壓縮前的樣式表比較。遺失了規則的樣式表會照原樣發布,並附上一則警告,指出被丟掉的內容。從 4.1.41 之後的版本起,只有建置進行壓縮時才執行這項檢查,因此 dev 會略過它。從 4.2.0 起,這則警告帶有代碼 W_CSS_PARSE。
url() 指向專案中任何地方都不存在的檔案時,會以 W_CSS_DEAD_REF 警告,樣式表的其餘部分照常發布。瀏覽器對那個位址回應 404。設定 EXTENSION_STRICT_REFS=true 可以讓建置以 E_CSS_DEAD_REF 失敗。
從 4.2.0 之後的版本開始,打包器無法解析的 url(),比如沒有副檔名的裸名稱,或者未安裝的作用域套件路徑,也會回報同樣的 W_CSS_DEAD_REF,而且 EXTENSION_STRICT_REFS=true 會讓建置以 E_CSS_DEAD_REF 失敗。4.2.0 及之前的版本把它回報為 W_ASSET_MISSING,嚴格參照模式也不會因此失敗。
開發行為
- Content script 的 CSS import 會參與 content script 的 HMR/重新掛載流程。
- Extension.js 會為純 CSS 的 content script 進入點加上開發輔助 script,讓更新可以傳播。
- 頁面 CSS 會走標準的頁面 HMR 流程。
- manifest 的修改會重新載入整個擴充功能。修改 manifest 中的 content script 進入點還會讓 dev 工作階段重新啟動編譯器,不需你操作。
模組與預處理器
- CSS Modules 在擴充功能頁面情境中運作得最好。
- 當你安裝相關相依套件時,Extension.js 會啟用 Sass/Less 支援。
- 如果專案引用了
.scss/.less檔案但沒有安裝預處理器,建置不會失敗,而是發出警告並把原始檔原封不動地複製過去(不編譯)。瀏覽器會把這份未編譯的原始碼當成壞掉的 CSS,那些畫面就會完全沒有樣式,所以請安裝預處理器以取得真正的編譯。 - 當 Extension.js 偵測到專案中的 PostCSS 設定、或你明確設定時,會自動執行 PostCSS。
最佳實務
- 刻意限制 content script 樣式範圍,降低與主機頁面的衝突。
- 為擴充功能頁面 UI 優先採用元件本地的 module 樣式。
- 明確保留預處理器與 PostCSS 設定,避免建置設定隨時間意外改變。
- 在持續整合(CI)中驗證被 manifest 欄位參考的 CSS 路徑。
後續步驟
- 在 dev 更新行為中了解更新結果。
- 進一步了解 CSS Modules。
- 進一步了解 PostCSS 整合。

