Chrome浏览器插件从Manifest V2迁移到Manifest V3迁移指南

栏目： chrome 发布时间：2025-03-11

最近自己开发的浏览器插件报如下错误信息：

Manifest version 2 is deprecated, and support will be removed in 2024. See https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline for details.

原因是我的这个插件的 manifest版本仍未 v2，chrome已不支持，要求升级到Manifest V3版本。

将Chrome浏览器插件从Manifest V2迁移到Manifest V3涉及多个方面的更改。以下是一个详细的迁移教程，帮助您顺利完成升级过程：

一、了解Manifest V3的主要变化

Manifest V3是Chrome浏览器扩展程序的新清单规范，相比Manifest V2，它带来了许多改进和安全性的提升。主要变化包括：

Service Worker替代Background Page：在Manifest V3中，不再使用背景页面（background page）或事件页面（event page），而是使用Service Worker来处理后台任务。
权限声明更加严格：V3对权限声明进行了更加严格的控制，不再支持动态请求权限，必须在安装时一次性请求所有必需的权限。
网络请求的修改：引入了新的declarativeNetRequest API来修改网络请求，替代了V2中的webRequest API，提供了更好的隐私保护。
内容脚本的加载方式调整：V3中内容脚本的注入需要在后台脚本中进行动态控制。
其他改进：包括插件图标管理方式的简化、存储方式的改进、卸载行为的优化以及更新机制的改进等。

二、迁移步骤

更新manifest.json文件

将manifest_version字段的值从2更改为3。

{
    "manifest_version": 3,
    ...
}

更新permissions和host_permissions字段。在Manifest V3中，主机权限是一个单独的字段，不再需要在permissions或optional_permissions中指定。

示例：

// Manifest V2
{
    "permissions": ["tabs", "bookmarks", "http://www.blogger.com/"],
    "optional_permissions": ["unlimitedStorage", "*://*/*"]
}

// Manifest V3
{
    "permissions": ["tabs", "bookmarks"],
    "optional_permissions": ["unlimitedStorage"],
    "host_permissions": ["http://www.blogger.com/"],
    "optional_host_permissions": ["*://*/*"]
}

更新action字段。Manifest V3引入了action字段，用于定义扩展程序的用户界面和交互行为，取代了V2中的browser_action和page_action字段。

{
    "action": {
        "default_popup": "popup.html",
        "default_icon": {
            "16": "images/icon16.png",
            "48": "images/icon48.png",
            "128": "images/icon128.png"
        }
    }
}

更新web_accessible_resources字段。在Manifest V3中，该字段用于限制哪些网站和扩展程序可以访问扩展程序中的资源。

// Manifest V2
{
    "web_accessible_resources": ["images/*", "style/extension.css", "script/extension.js"]
}

// Manifest V3
{
    "web_accessible_resources": [
        {
            "resources": ["images/*"],
            "matches": ["*://*/*"]
        },
        {
            "resources": ["style/extension.css", "script/extension.js"],
            "matches": ["https://example.com/*"]
        }
    ]
}

迁移到Service Worker
- 在Manifest V3中，使用service_worker字段来定义一个Service Worker，用于处理事件和后台任务。将manifest.json中的background.scripts替换为background.service_worker。
```
// Manifest V2
{
    "background": {
        "scripts": ["backgroundContextMenus.js", "backgroundOauth.js"],
        "persistent": false
    }
}

// Manifest V3
{
    "background": {
        "service_worker": "service_worker.js",
        "type": "module"  // 如果使用ES模块，则需要此字段
    }
}
```
- 注意：Service Worker在主线程以外运行，不会干扰扩展程序内容，因此需要将访问DOM或window接口的调用移至其他API或屏幕外文档中。

更新网络请求的处理方式

在Manifest V3中，使用declarativeNetRequest API来修改网络请求，替代V2中的webRequest API。

首先，在manifest.json中添加declarative_net_request权限和静态规则集。

{
    "name": "My extension",
    "permissions": ["declarativeNetRequest", "declarativeNetRequestFeedback"],
    "declarative_net_request": {
        "rule_resources": [
            {
                "id": "ruleset_1",
                "enabled": true,
                "path": "rules_1.json"
            }
        ]
    }
}

然后，在扩展程序目录下创建rules_1.json文件，定义修改网络请求的规则。

[
    {
        "id": 1,
        "priority": 1,
        "condition": {
            "regexFilter": "https://XXX.XXX.XXX/api/*",
            "resourceTypes": ["xmlhttprequest"]
        },
        "action": {
            "type": "modifyHeaders",
            "requestHeaders": [
                {
                    "header": "h1",
                    "operation": "set",
                    "value": "v4"
                },
                {
                    "header": "foo",
                    "operation": "remove"
                }
            ]
        }
    }
]

更新内容脚本的加载方式

在Manifest V3中，内容脚本的注入需要在后台脚本中进行动态控制。使用chrome.scripting.executeScript方法注入内容脚本。

// Manifest V2
chrome.tabs.executeScript({
    file: 'content-script.js'
});

// Manifest V3
async function getCurrentTab() {
    // 获取当前活动的标签页
}

let tab = await getCurrentTab();
chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ['content-script.js']
});

其他注意事项
- 图标管理：在Manifest V3中，只需提供一个16x16的图标，Chrome会自动将其放大以适应不同的显示场景。
- 存储方式：使用新的存储API（如chrome.storage.sync和chrome.storage.local）来管理扩展程序的存储。
- 卸载行为：在Manifest V3中，Chrome会在插件卸载时自动删除其存储的数据，保护用户隐私。
- 更新机制：Chrome提供了自动更新机制，当开发者发布新版本时，用户的插件会自动进行更新。

三、测试与发布

测试插件：在迁移完成后，彻底测试插件的功能，确保所有功能在新版本中正常工作。
发布插件：测试通过后，将插件发布到Chrome Web Store，供用户下载和使用。

请注意，迁移过程中可能会遇到一些兼容性问题，需要根据具体情况进行调试和解决。同时，建议参考Chrome官方文档和社区资源，以获取最新的迁移指南和支持。

本文地址：https://www.tides.cn/p_chrome-migrate-from-manifest-v2-to-manifest-v3

标签： chrome插件

Chrome浏览器插件从Manifest V2迁移到Manifest V3迁移指南

一、了解Manifest V3的主要变化

二、迁移步骤

三、测试与发布

推荐阅读