Chrome扩展Content Scripts注入JS的机制与权限配置详解

一、Content Scripts 执行机制：隔离世界（Isolated World）

要透彻理解 Content Scripts 的行为，首先必须理解 Chromium 内核的“隔离世界”（Isolated World）机制。浏览器在渲染网页时，每一个页面都对应一个主执行上下文（Main World），这里运行着网页开发者编写的原生 JavaScript 代码。当 Chrome 扩展向该页面注入 Content Scripts 时，浏览器并不会将其直接并入 Main World，而是开辟一个彼此并行的独立执行世界。

这种设计保证了双向安全性与稳定性：一方面，宿主网页无法通过恶意篡改原型链（如修改 Array.prototype 或劫持 fetch）入侵扩展代码；另一方面，扩展中定义的任何全局变量、函数和第三方依赖库，也不会污染宿主网页的命名空间导致业务崩溃。

• 共享的内容（DOM 可见）：两个世界共享同一个底层的 DOM 树。Content Scripts 可以通过标准的 document.getElementById、querySelector 或 MutationObserver 自由增删改查页面的 DOM 节点、监听点击与键盘事件、注入内联 CSS 样式。
• 隔离的内容（JS 变量不通）：Content Scripts 拥有独立的 window 对象和原型链。网页脚本挂载在 window.myAppConfig 上的数据，Content Scripts 无法直接通过 window.myAppConfig 读取（得到的结果是 undefined）；反之，Content Scripts 挂载在自己 window 上的数据，宿主网页也毫无感知。

如果确实需要访问宿主 window 对象怎么办？

在 Chrome 111 及以后的版本中，Manifest V3 为 Content Scripts 新增了 world 配置项。如果你需要拦截页面原生的 JavaScript 变量或监听宿主自定义事件，可以直接将运行环境显式指定为 "MAIN"：

// 声明在 Main World 执行的静态注入
{
  "content_scripts": [
    {
      "matches": ["https://example.com/*"],
      "js": ["injected-main.js"],
      "world": "MAIN" // 默认为 "ISOLATED"
    }
  ]
}

二、三类 JS 注入机制的实现与应用场景

在现代 Chrome 扩展架构中，向网页注入 JavaScript 共有三种成熟的路径：声明式静态注入、编程式动态注入与动态注册注入。开发者应当根据触发条件与业务灵活性做出精准选型。

1. 声明式静态注入（manifest.json content_scripts）

静态注入是最传统也最稳定的方式。扩展在安装阶段就通过 manifest.json 明确声明：当用户访问符合 URL 规则的页面时，由浏览器底层引擎自动将指定的脚本加载至对应标签页。

{
  "manifest_version": 3,
  "name": "DOM Enhancer Extension",
  "version": "1.0.0",
  "content_scripts": [
    {
      "matches": ["https://*.github.com/*"],
      "js": ["content-parser.js"],
      "css": ["styles.css"],
      "run_at": "document_idle",
      "all_frames": false,
      "match_about_blank": false
    }
  ]
}

静态配置中三个决定性的参数：

• run_at：决定 JS 代码注入的精确时机（具体时机差异详见后文生命周期图解）。支持 document_start、document_end 和 document_idle（默认）。
• all_frames：为 true 时，网页内嵌套的所有 <iframe> 只要匹配规则也会一并注入；默认仅注入最顶层主框架（Top frame）。
• match_about_blank：是否在匹配父级页面的 about:blank 或 about:srcdoc 框架中注入代码。

2. 编程式动态注入（chrome.scripting.executeScript）

并非所有扩展都需要无差别地在页面加载时执行脚本。例如划词翻译、页面截图提取器、密码一键填充工具，通常只在用户点击扩展图标（Action）、触发快捷键或右键菜单时按需启动。在 Manifest V3 中，旧版的 chrome.tabs.executeScript 已被彻底废弃，取而代之的是现代化的 chrome.scripting.executeScript。

实现编程式注入必须在 manifest.json 中声明 scripting 权限：

{
  "permissions": ["scripting", "activeTab"],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_title": "点击注入执行"
  }
}

在后台 background.js 中监听用户交互并触发注入：

// background.js (Service Worker)
chrome.action.onClicked.addListener(async (tab) => {
  if (!tab.id) return;

  try {
    // 形式一：直接注入并执行一个独立的 JS 文件
    await chrome.scripting.executeScript({
      target: { tabId: tab.id },
      files: ["injected-action.js"]
    });

    // 形式二：注入内联函数并向其安全传递实参，获取执行返回值
    const results = await chrome.scripting.executeScript({
      target: { tabId: tab.id },
      args: ["高亮提示", "#FAF7F1"],
      func: (titleText, themeColor) => {
        document.title = `[${titleText}] ` + document.title;
        document.body.style.backgroundColor = themeColor;
        return { currentUrl: location.href, readyState: document.readyState };
      }
    });

    const pageState = results[0]?.result;
    console.log("注入执行成功，页面当前返回状态：", pageState);
  } catch (err) {
    console.error("动态注入失败：", err.message);
  }
});

3. 动态注册注入（chrome.scripting.registerContentScripts）

动态注册结合了静态注入与编程式注入的双重优势：它无需在 manifest.json 中把所有网址硬编码写死，允许扩展在运行时根据用户在设置界面的选择，持久化地注册、注销或更新 Content Scripts 规则。即便浏览器重启，已注册的规则依然有效。

// 运行时动态注册自定义网址规则（适用于用户脚本管理类扩展）
async function setupDynamicScript(userDomain) {
  const scriptId = "user-custom-rule";

  // 注册前先尝试注销同名规则，避免重复注册异常
  const existing = await chrome.scripting.getRegisteredContentScripts();
  if (existing.some(s => s.id === scriptId)) {
    await chrome.scripting.unregisterContentScripts({ ids: [scriptId] });
  }

  // 注册新规则
  await chrome.scripting.registerContentScripts([{
    id: scriptId,
    matches: [`https://${userDomain}/*`],
    js: ["custom-enhancement.js"],
    runAt: "document_idle",
    persistAcrossSessions: true
  }]);
  console.log(`已为 ${userDomain} 动态注册内容脚本`);
}

三、权限配置规范与最小权限原则（Manifest V3）

在 Manifest V2 时代，扩展常常直接在 permissions 字段中声明 "<all_urls>"，这导致安装时浏览器会弹窗警告“该扩展可以读取和更改您访问的所有网站上的所有数据”，极大地损害了用户信任与扩展上架审核效率。

在现代 Manifest V3 中，Chrome 引入了更加严格的权限分离机制：

1. permissions 与 host_permissions 的严格分离

在 MV3 中，纯 API 能力权限与目标网页主机权限被正式拆分：

• permissions：仅用于声明扩展专有 API 能力，例如 ["scripting", "storage", "alarms", "contextMenus"]。
• host_permissions：专门声明扩展有权访问或注入脚本的外部网页域名匹配模式，例如 ["https://api.github.com/*", "*://*.zhihu.com/*"]。

{
  "name": "安全权限示例",
  "manifest_version": 3,
  "permissions": [
    "scripting",
    "storage"
  ],
  "host_permissions": [
    "https://developer.chrome.com/*"
  ]
}

2. activeTab：免去高危弹窗警告的核心特权

如果你开发的是一款“用户主动点击才工作”的插件（例如页面笔记、字数统计、颜色吸管），强烈建议使用 activeTab 权限代替广泛的 host_permissions。

• 零警告安装：声明 activeTab 在用户安装时不会产生任何“读取您的网页数据”警告。
• 临时提权：当且仅当用户主动与扩展交互（点击了 Action 扩展图标、点击了扩展右键菜单或按下了扩展快捷键）的瞬间，扩展获得对当前激活标签页的临时 host_permissions。
• 生命周期安全：该权限随着该标签页关闭或跳转到新网址自动撤销。结合 chrome.scripting.executeScript，可完成任意 DOM 操作。

3. 匹配模式（Match Patterns）的编写边界与防错

无论是在静态 content_scripts.matches 还是在 host_permissions 中，匹配规则必须严格遵循 <scheme>://<host>/<path> 结构：

• https://*.example.com/*：匹配 example.com 及其所有二级域名下的所有路径。
• *://localhost/*：仅匹配本地端口无指定或特定端口协议。
• 禁止规则：https://*/* 是非法格式（主机名通配符后不能留空），若需全域通配必须使用 <all_urls> 或 *://*/*。
• 受限域无法注入：Chrome 绝不允许任何扩展向 chrome://*、Chrome 应用商店（https://chromewebstore.google.com/*）注入任何 Content Scripts。在这些页面调用 executeScript 将直接抛出运行时异常。

四、跨世界通信与资源访问安全边界

由于 Isolated World 与主世界及 Background Service Worker 各自独立，构建完整的扩展功能必须依赖严格规范的通信体系。

1. Content Script 与 Background Service Worker 通信

Content Script 拥有极少量的 chrome.* API 访问权（仅限 runtime、i18n、storage 的部分受限操作）。当需要进行跨域网络请求、调用 Cookie 或操作标签页管理时，必须通过 chrome.runtime.sendMessage 委派后台处理。

// content.js 发送单向或带响应的消息
(async () => {
  const response = await chrome.runtime.sendMessage({
    action: "FETCH_REMOTE_DATA",
    payload: { targetId: 1024 }
  });
  console.log("收到 Background 响应：", response);
})();

// background.js (Service Worker) 监听与回复
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === "FETCH_REMOTE_DATA") {
    // 执行跨域请求或其他特权 API
    fetch(`https://api.example.com/items/${message.payload.targetId}`)
      .then(res => res.json())
      .then(data => sendResponse({ success: true, data }))
      .catch(err => sendResponse({ success: false, error: err.message }));
    
    return true; // 必须返回 true 以表明将异步调用 sendResponse
  }
});

2. Content Script 与宿主网页 Main World 通信

如果页面原生 JS 需要将用户登录凭据或渲染状态告诉 Content Script，或者 Content Script 需要通知宿主框架触发局部刷新，最佳实践是通过带类型过滤的 window.postMessage 或 CustomEvent：

// content.js (Isolated World) 监听宿主抛出的安全消息
window.addEventListener("message", (event) => {
  // 严格限制消息源必须来自当前窗口
  if (event.source !== window) return;
  if (event.data?.type === "PAGE_AUTH_STATUS") {
    console.log("安全捕获宿主用户状态：", event.data.user);
  }
});

3. 资源引入声明（web_accessible_resources）

当 Content Script 向页面 DOM 中追加扩展内部的图片、音频或 HTML 模板（例如通过 chrome.runtime.getURL("images/logo.png")）时，若未在 manifest.json 中声明 web_accessible_resources，浏览器将出于安全防御机制直接拦截请求（报 Denying load of chrome-extension://...）。

// manifest.json 中的精细化资源开放声明
{
  "web_accessible_resources": [
    {
      "resources": ["images/logo.png", "panel.html"],
      "matches": ["https://*.example.com/*"],
      "use_dynamic_url": true // 防止网站指纹探测扩展的存在
    }
  ]
}

五、实战排错、调试技巧与选型决策

在开发调试 Content Scripts 期间，有几个极易出现的高频痛点，只要掌握其机理即可迅速定位解决：

Chrome 扩展在向现代 Manifest V3 演进的过程中，核心理念便是强化安全性、规范生命周期以及消除过度权限。充分理解 Content Scripts 隔离世界的物理边界，根据业务场景合理组合 activeTab、scripting 与静态声明，不仅能够避免页面冲突与安全隐患，更能让扩展在审核与发布阶段畅行无阻。