Vue Chrome扩展Manifest V2迁移至V3适配方案咨询

一、修改后的完整V3版manifest.json #

{
  "manifest_version": 3,
  "version": "0.9.9",
  "name": "AAAAAA",
  "description": "BBBBBB",
  "homepage_url": "https://AAA.co",
  "permissions": [
    "notifications",
    "storage",
    "activeTab",
    "unlimitedStorage"
  ],
  "icons": {
    "16": "icons/icon.png",
    "48": "icons/icon.png",
    "128": "icons/icon.png",
    "256": "icons/icon.png",
    "512": "icons/icon.png",
    "1024": "icons/icon.png"
  },
  "background": {
    "service_worker": "js/background.js"
  },
  "content_scripts": [
    {
      "matches": [
        "file://*/*",
        "http://*/*",
        "https://*/*"
      ],
      "js": [
        "js/content-script.js"
      ],
      "run_at": "document_start",
      "all_frames": false
    }
  ],
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon.png",
      "48": "icons/icon.png",
      "128": "icons/icon.png",
      "256": "icons/icon.png",
      "512": "icons/icon.png",
      "1024": "icons/icon.png"
    }
  },
  "content_security_policy": {
    "extension_pages": "script-src 'self' 'sha256-ZgDy59Dh4jH9g/vcPYFpoQ1wumB4IdPEOS1BJc08i+Y='; object-src 'self';"
  }
}

二、核心配置改动说明 #

• 版本声明：将manifest_version字段值从2修改为3，这是V3扩展的强制标识
• 工具栏API统一：V3废弃了browser_action/page_action的区分，统一合并为action字段，原有弹窗、图标配置直接平移即可
• 后台逻辑改造：V3取消了持久后台页，原有的background.scripts+persistent: true配置替换为service_worker单入口配置，后台脚本运行在Service Worker上下文，不再支持DOM访问
• CSP格式调整：V3将原有的单字符串CSP配置改为对象结构，扩展自有上下文（后台、弹窗、扩展页面）的CSP规则放在extension_pages字段下
• 权限兼容：你当前配置的notifications/storage/activeTab/unlimitedStorage权限在V3下完全兼容，不需要额外调整
• 图标配置：原有图标路径配置无需修改，V3对图标尺寸的要求和V2一致

注意：V3扩展自有上下文强制禁止unsafe-eval、禁止加载执行远程域名下的脚本，你原有CSP里的unsafe-eval、https://cdn.segment.com配置无法在扩展上下文中生效：

• 把Segment SDK源码下载到本地扩展目录，用相对路径引入，不要动态拉取CDN资源，否则会被CSP拦截，也过不了Chrome商店审核
• 调整项目构建配置，移除代码中的eval逻辑（比如Webpack构建时不要用eval类SourceMap，生产模式构建默认会移除eval相关代码）
• 如果确实需要在普通网页中执行远程脚本，把相关逻辑放到content script中实现，content script继承所在页面的CSP规则，不受扩展CSP限制

三、配套代码调整要点 #

• 后台脚本适配：V3的Service Worker仅支持单JS入口，如果原background配置了多个脚本文件，需要先打包合并为单个文件；同时Service Worker上下文没有window/document等DOM对象，如果原background.js里有DOM操作逻辑，把这部分拆分到popup页或者content script中，通过chrome.runtime.sendMessage做消息通信
• API替换：原V2中调用chrome.browserAction系列API的代码，全部替换为chrome.action，比如点击工具栏图标的监听事件从chrome.browserAction.onClicked改为chrome.action.onClicked
• 生命周期适配：Service Worker会在闲置时被浏览器休眠，不要在后台脚本的全局变量里存持久状态，所有需要留存的数据统一存到chrome.storage中；如果用了长连接消息通信，要做好休眠后的重连逻辑
• 文件访问权限：V3下file://*/*的匹配规则默认不生效，需要用户在扩展详情页手动开启「允许访问文件网址」开关才能注入脚本到本地文件页，这点可以在扩展说明里告知用户
• 请求拦截适配：如果原代码用了chrome.webRequest系列API拦截修改网络请求，V3下需要替换为chrome.declarativeNetRequestAPI，同时在permissions里新增declarativeNetRequest权限，你当前配置没用到相关逻辑可以忽略

四、上传前校验 #

• 打开Chrome扩展管理页（chrome://extensions/），开启开发者模式，选择「加载已解压的扩展程序」导入修改后的项目，验证核心功能：弹窗正常打开、content script正常注入、通知推送、存储读写是否符合预期
• 功能验证无报错后，打包成zip包即可上传Chrome应用商店，满足商店上架要求

内容的提问来源于stack exchange，提问作者Guowang