Chrome 扩展 Manifest V3 迁移：单服务工作线程与脚本注入实践-js教程-PHP中文网

Chrome 扩展 Manifest V3 迁移：单服务工作线程与脚本注入实践

霞舞

发布： 2025-07-14 20:22:01

原创

965人浏览过

chrome 扩展 manifest v3 迁移：单服务工作线程与脚本注入实践

本文旨在指导开发者将 Chrome 扩展从 Manifest V2 迁移至 Manifest V3，重点解决多背景脚本合并为单一服务工作线程的问题，并详细阐述 chrome.tabs.executeScript 到 chrome.scripting.executeScript 的 API 迁移。通过合并事件监听器和正确使用新的脚本注入方法，确保扩展在 Manifest V3 环境下高效、稳定运行。

1. Manifest V3 背景脚本架构概览

Manifest V3 对 Chrome 扩展的背景脚本架构进行了重大调整。最核心的变化包括：

单一服务工作线程 (Service Worker)：Manifest V2 允许通过 background.scripts 字段指定多个背景脚本文件，这些脚本在独立的持久性背景页面中运行。而在 Manifest V3 中，背景脚本被替换为单一的服务工作线程，通过 background.service_worker 字段指定。这个服务工作线程是非持久性的，会在空闲时终止，并在需要时重新激活。
弃用 chrome.tabs.executeScript：为了增强安全性，Manifest V3 弃用了 chrome.tabs.executeScript API。取而代之的是功能更强大、权限管理更细粒度的 chrome.scripting.executeScript API。

本教程将围绕这两个关键变化，指导您如何将原有的多个背景脚本逻辑合并到一个服务工作线程中，并正确使用新的脚本注入方式。

2. 合并多背景脚本逻辑

在 Manifest V2 中，您可能拥有类似以下配置的 manifest.json：

{
  "name": "My Extension",
  "version": "1.0",
  "manifest_version": 2,
  "background": {
    "scripts": ["sw.js", "swTwo.js"]
  },
  "permissions": [
    "webRequest",
    "tabs",
    "<all_urls>"
  ]
}

登录后复制

以及两个独立的背景脚本文件 sw.js 和 swTwo.js，分别包含不同的 chrome.webRequest.onCompleted 监听器：

sw.js (Manifest V2 示例)

chrome.webRequest.onCompleted.addListener(zeineth => {
  if (zeineth.method !== "POST") {
    return;
  }
  chrome.tabs.executeScript(zeineth.tabId, {file: "script.js"});
}, {urls: ["https://example.com/api/*"]});

登录后复制

swTwo.js (Manifest V2 示例)

chrome.webRequest.onCompleted.addListener(cristinia => {
  if (cristinia.method !== "POST") {
    return;
  }
  chrome.tabs.executeScript(cristinia.tabId, {file: "scriptTwo.js"});
}, {urls: ["https://another-example.com/data/*"]});

登录后复制

在 Manifest V3 中，所有背景逻辑必须合并到一个服务工作线程文件（例如 service_worker.js）中。这意味着您需要将所有 chrome.webRequest.onCompleted 监听器以及它们内部的逻辑整合到一个文件中。

合并后的 service_worker.js (Manifest V3 准备)

// 第一个 webRequest 监听器
chrome.webRequest.onCompleted.addListener(details => {
  if (details.method !== "POST") {
    return;
  }
  // 在这里调用 chrome.scripting.executeScript，注意参数变化
  // 稍后会详细解释
}, {urls: ["https://example.com/api/*"]});

// 第二个 webRequest 监听器
chrome.webRequest.onCompleted.addListener(details => {
  if (details.method !== "POST") {
    return;
  }
  // 在这里调用 chrome.scripting.executeScript，注意参数变化
  // 稍后会详细解释
}, {urls: ["https://another-example.com/data/*"]});

登录后复制

3. 迁移 chrome.tabs.executeScript 到 chrome.scripting.executeScript

chrome.scripting.executeScript 是 Manifest V3 中用于在页面中注入脚本的新 API。它与 chrome.tabs.executeScript 有以下主要区别：

火龙果写作

用火龙果，轻松写作，通过校对、改写、扩展等功能实现高质量内容生产。

106

查看详情

权限要求：使用 chrome.scripting API 需要在 manifest.json 中声明 scripting 权限。
参数结构：它接受一个配置对象作为参数，而不是直接的 tabId 和 details 对象。
目标指定：通过 target 属性来指定目标选项卡。
脚本来源：可以通过 files 数组指定要注入的文件，也可以通过 function 属性直接提供一个函数。

以下是两种 chrome.webRequest.onCompleted 监听器合并后，并使用 chrome.scripting.executeScript 的正确实现：

service_worker.js (Manifest V3 完整示例)

// 监听第一个 URL 模式的 POST 请求完成事件
chrome.webRequest.onCompleted.addListener(details => {
  if (details.method !== "POST") {
    return;
  }
  console.log("捕获到第一个 POST 请求:", details.url);

  // 使用 chrome.scripting.executeScript 注入 script.js
  chrome.scripting.executeScript({
    target: {tabId: details.tabId}, // 指定目标 tabId
    files: ['script.js']           // 指定要注入的脚本文件
  }).then(() => {
    console.log("script.js 已注入并执行完毕。");
  }).catch(error => {
    console.error("注入 script.js 失败:", error);
  });
}, {urls: ["https://example.com/api/*"]}); // 监听的 URL 模式

// 监听第二个 URL 模式的 POST 请求完成事件
chrome.webRequest.onCompleted.addListener(details => {
  if (details.method !== "POST") {
    return;
  }
  console.log("捕获到第二个 POST 请求:", details.url);

  // 使用 chrome.scripting.executeScript 注入 scriptTwo.js
  chrome.scripting.executeScript({
    target: {tabId: details.tabId}, // 指定目标 tabId
    files: ['scriptTwo.js']        // 指定要注入的脚本文件
  }).then(() => {
    console.log("scriptTwo.js 已注入并执行完毕。");
  }).catch(error => {
    console.error("注入 scriptTwo.js 失败:", error);
  });
}, {urls: ["https://another-example.com/data/*"]}); // 监听的 URL 模式

登录后复制

关键点说明：

target: {tabId: details.tabId}: 这是指定脚本注入到哪个标签页的关键。details.tabId 是从 webRequest 事件中获取的当前请求所在的标签页ID。
files: ['script.js']: 这是一个数组，包含一个或多个要注入的脚本文件路径。
Promise 返回值: chrome.scripting.executeScript 返回一个 Promise，您可以使用 .then() 和 .catch() 来处理脚本注入成功或失败的情况。

4. 更新 manifest.json

为了使上述 Manifest V3 代码正常工作，您的 manifest.json 文件也需要进行相应的更新：

manifest_version 必须设置为 3。
background 字段应更改为 service_worker。
permissions 字段需要添加 scripting 权限。

manifest.json (Manifest V3 完整示例)

{
  "name": "My MV3 Extension",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service_worker.js"
  },
  "permissions": [
    "webRequest",
    "scripting"
  ],
  "host_permissions": [
    "https://example.com/*",
    "https://another-example.com/*"
  ]
}

登录后复制

注意事项：

host_permissions: 在 Manifest V3 中，对于需要访问特定主机或 URL 的 API (如 webRequest 或 scripting 在某些情况下)，您需要使用 host_permissions 字段明确声明这些主机。"<all_urls>" 仍然可用，但建议尽可能缩小权限范围。
urls 错误提示: 原始问题中提到的 "url error" 可能是因为尝试将 urls 属性放在 chrome.scripting.executeScript 的参数对象中。urls 属性仅用于 chrome.webRequest 监听器的过滤器，而不是脚本注入API。请确保 urls 仅存在于 webRequest 监听器的第二个参数中。

5. 总结与最佳实践

将 Chrome 扩展从 Manifest V2 迁移到 Manifest V3 是一个重要的过程，涉及到背景脚本架构和权限模型的根本性变化。

单一服务工作线程: 接受并适应服务工作线程的非持久性生命周期。这意味着您的背景逻辑需要能够处理服务工作线程的启动和终止，并使用持久化存储（如 chrome.storage.local）来保存状态。
权限最小化: 始终遵循最小权限原则，只请求扩展功能所需的权限。利用 host_permissions 精确指定可访问的域。
异步操作: chrome.scripting.executeScript 是异步的，返回一个 Promise。务必使用 async/await 或 .then().catch() 来处理其结果，确保代码的执行顺序和错误处理。
调试服务工作线程: 在 Chrome 扩展管理页面（chrome://extensions）中，为您的扩展启用开发者模式，并点击服务工作线程的“Inspect”链接，可以打开开发者工具来调试服务工作线程。

通过理解并实施这些改变，您可以成功地将您的 Chrome 扩展更新到 Manifest V3，以符合最新的安全和性能标准。

以上就是Chrome 扩展 Manifest V3 迁移：单服务工作线程与脚本注入实践的详细内容，更多请关注php中文网其它相关文章！