跳轉至

建立 2026-09-17 更新 2026-09-17

Content Scripts

Content Script 是唯一能直接讀取與修改網頁 DOM 的程式碼,執行在瀏覽器實際載入的網頁環境中,但與網頁本身的 JavaScript 是隔離的(稱為「隔離世界」,isolated world)——你的擴充功能程式碼看不到網頁定義的變數與函式,網頁也看不到你的,避免互相干擾或衝突。

兩種注入方式

靜態宣告(在 manifest.json)

適合「只要符合條件的網頁載入,就一定要執行」的情境:

manifest.json(片段)
{
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["content.js"],
      "css": ["content.css"],
      "run_at": "document_idle"
    }
  ]
}
  • matches:符合的網址規則(match pattern),只有符合的網頁才會注入。
  • run_atdocument_start(頁面開始解析前)、document_end(DOM 解析完成)、document_idle(預設,頁面閒置時,通常是最安全的選擇)。

動態注入(chrome.scripting)

適合「只有使用者主動觸發時才需要」的情境,可以搭配 activeTab 權限,不需要在 host_permissions 寫死網域:

background.js
chrome.action.onClicked.addListener(async (tab) => {
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ["content.js"],
  });
});

動態注入更符合權限最小化原則(見 權限與安全性),因為只有使用者按下按鈕的那一刻才會執行,Chrome Web Store 審核時也比較容易通過。

實際範例:抓取頁面標題並回傳

content.js
const title = document.querySelector("h1")?.textContent ?? document.title;

chrome.runtime.sendMessage({ type: "PAGE_TITLE", title });

Content Script 可以用一般的 DOM API(document.querySelectoraddEventListener 等)操作頁面,並透過 訊息傳遞 把結果送回 Background 或 Popup。

限制與注意事項

  • 不能直接使用大部分的 Chrome API(例如 chrome.storagechrome.tabs 多數方法都不能呼叫),需要透過訊息傳遞請 Background 代為執行。
  • 無法存取瀏覽器內部頁面(chrome://、Chrome Web Store 本身)與部分特殊頁面。
  • 同一個 matches 規則的擴充功能可能同時被多個分頁注入,撰寫時要留意重複執行的副作用(例如避免重複插入相同的 UI 元素)。

下一步

Content Script 負責「看得到、改得了網頁」,接著看 Popup 與 Options 頁面,了解使用者與擴充功能互動的介面。