chrome V3插件入门到放弃，Plasmo不完全使用指南-Toy模板网

这篇具有很好参考价值的文章主要介绍了chrome V3插件入门到放弃，Plasmo不完全使用指南。希望对大家有所帮助。如果存在错误或未考虑完全的地方，请大家不吝赐教，您也可以点击"举报违法"按钮提交疑问。

chrome V3插件入门到放弃，Plasmo不完全使用指南

没有插件的浏览器是没有灵魂的。今天来近距离感受一下chrome的灵魂

开始之前了解一下灵魂chrome插件的版本。

chrome V3插件入门到放弃，Plasmo不完全使用指南

Chrome 浏览器从88版本开始支持MV3啦（即Manifest Version 3），现在浏览器版本都100+了。而MV2（即Manifest Version 2）将会在2023年 退休 。所以今天要讲的就是MV3版本

后续的文章中，因为我没有魔法，所以贴出来的文档地址都是国内可以访问的文档（有条件的同学可以直接看谷歌的原文档 https://developer.chrome.com/docs/extensions/mv3/）

版本变更的变动

manifest.json 作为插件的配置清单最能体现相关的变动了从manifest.json 参考文档可以很清楚地看到配置升级其实主要加了2个「action」和「host_permissions」

比较小的变动

Host Permissions

在V2中，有两种方法为你的api或任何主机获得权限，要么在 permissions 数组或 optional_permissions 数组。

{
  "permissions": ["https://xxxx.com/*"]
}

在V3中，所有主机权限现在都单独存在一个新数组中，该数组的键为 host_permissions。主机权限不再与其他权限一起添加。

{
  "host_permissions": ["https://xxx.com/*"]
}

Actions

在V2中，分为 browser_action 和 page_action 。

browser_action 更多是负责插件的icon的切换等操作。参考文档： API-browserAction
而page_action 更多是针对某个页面进行地址栏的操作参考文档：API-pageAction

感兴趣的可以在MDN插件开发文档里面看一看。

在V3中，都统一合并为 action 。参考文档：API-action

content_security_policy 变动

在V2的manifest.json 的 content_security_policy 配置是一个字符串类型。升级到 V3 后变成了一个对象类型。详细的变更看文档会更加清晰：content_security_policy 参考文档

web_accessible_resources

详细变更参考 web_accessible_resources

// v2 写法
{
	"web_accessible_resources": ["images/my-image.png"]
}

// v3 写法
{
  // …
  "web_accessible_resources": [
    {
      "resources": [ "test1.png", "test2.png" ],
      "matches": [ "https://web-accessible-resources-1.glitch.me/*" ]
    }, {
      "resources": [ "test3.png", "test4.png" ],
      "matches": [ "https://web-accessible-resources-2.glitch.me/*" ],
      "use_dynamic_url": true
    }
  ],
  // …
}

不在允许远程托管代码

以前一些功能可以依赖于网络请求动态加载，V3 则不允许这样的操作了

不再支持加载远程托管的代码主要出于两个原因：
- 安全因素，远程代码总是有不安全因素存在
- Chrome 在审核提交的插件时更可靠，更高效，不需要再去关注远程代码，只需要审核包内的代码即可。

只能把以前通过链接加载的js下载到插件包中，改改资源引入就好~

Promises

V3 现在原生支持 Promise。许多常用 API 现在都支出，最终所有合适的 API 都会支持 Promise。

如果使用 callback，就不会返回 Promise，优先执行 callback。

较大的变动

将 Background Scripts 改造成 Service Workers

在V2中，Background是可以通过 persistent 配置来确保页面时候需要 持久化 。而且还能支持 .html

"background": {
  "scripts": ["background-script.js"],
  "persistent": false
}

//  或
"background": {
  "page": "background-page.html",
  "persistent": false
}

很多小技巧都依赖于 html 这特性，把数据挂载在 background 的 window 对象上进行数据中转

V3 则是强制使用了 Service Workers，禁止了持久化。background只能使用js文件

"background": { "scripts": ["background.js"] },

网络拦截，使用新的declarativeNetRequest来修改请求

这个变动非常的大，在本文后面详细讲这一块的内容。而且 MDN 文档还没更新 declarativeNetRequest 相关的内容，等下要找个新文档来看

弃用的API

chrome.extension.getExtensionTabs()
chrome.extension.getURL()
chrome.extension.lastError
chrome.extension.onRequest
chrome.extension.onRequestExternal
chrome.extension.sendRequest()
chrome.tabs.getAllInWindow()
chrome.tabs.getSelected()
chrome.tabs.onActiveChanged
chrome.tabs.onHighlightChanged
chrome.tabs.onSelectionChanged
chrome.tabs.sendRequest()
chrome.tabs.selected

在查看 MDN 文档时会有相关的提示

chrome V3插件入门到放弃，Plasmo不完全使用指南

使用chrome官方文档时的提示

chrome V3插件入门到放弃，Plasmo不完全使用指南

查阅官方文档时，那些标签也能帮助到我们。
Promise 标签：支持 Promise
<=MV2 标签：该API仅在V2前支持
>=MV3标签 ：该API在V3后支持
Deprecated 标签：已废弃的 API

使用 Plasmo 开发

都2022年了，或许每次开发一些新东西的时候你都会在想：

我要用什么技术栈？Vue3/React?
开发插件，能不能用npm上的包啊，如果能的话我是不是还得配webpack或者vite？
webpack的话，我是不是得配置多个入口和出口才能满足插件的入口要求

好麻烦啊，上github找找有没有现成的。
好像都还可以，收藏吃灰，下次在开发把

不要下次了！就这次把，强烈推荐 Plasmo

官网： plasmo
github： PlasmoHQ/plasmo

官方自己的介绍（说的非常的朴素，我一个路人都觉得这功能写少了）
chrome V3插件入门到放弃，Plasmo不完全使用指南

作为一个过来人的感受，我只能说用 Plasmo 很舒服~

Plasmo 上手体验

想体验先安装Plasom，快速上手文档： getting-started

注意下自己的 pnpm 版本或者 npm 版本，我用的是pnpm

# 使用下面的命令进行项目初始化

pnpm dlx plasmo init
# OR npm v7
npm x plasmo init

这时候如果你是新手，建议直接从 PlasmoHQ/examples 找一个模版看一下他的目录结构，然后找到自己想要的功能进行开发

比如我想基于vue，开发一个 popup 的界面。可以在示例中直接找到 examples/with-vue

还有各种技术栈（React，svelte，tailwindcss，nextjs…）

不止 popup 页，还有 background, devtool, options 页面都能在 examples 仓库找到相关的模版

chrome V3插件入门到放弃，Plasmo不完全使用指南

Plasmo 有一个很方便的地方在于：我开发 popup 的页面，我只需要有一个叫 popup.(tsx | vue) 的文件，开发background，只需要有一个 background.ts 文件。

这些作为对应的入口文件我们只需要按命名规范写好（甚至可以写成 popup/index.vue ），剩下的 manifest.json 配置就交给 Plasmo

从安装脚手架到现在，我们都没见到 manifest.json 文件，更加说明了这些入口不需要我们显示声明

Plasmo 修改 manifest.json 配置

虽然没有 manifest.json ，但是该要写的配置还是得写的

比如我们开发一个针对 http://xxxx.com 网页的插件，首先得申请权限 host_permissions

这部分配置写在了 package.json 中的 "manifest" 下。包括申请权限，注入资源都在 "manifest" 中去配置。

// package.json
{
	// ...
	"manifest": {
		"permissions":["declarativeNetRequest"], // 获取拦截网络请求的权限

		// 页面注入静态资源
		"web_accessible_resources": [
			{
				"resources": [
					"inject.js"
				],
				// 针对全部界面注入
				"matches": [
					"<all_urls>"
				]
			}
		],

		// 针对哪些页面生效
		"host_permissions": [
			"https://xxxx.com/*",
			"http://xxxx.com/*"
		]
	}
	// ...
}

有个例外就是 content.ts (注入到网页的那部分内容)

因为 content.ts 对应的配置是 MDN文档：manifest.json/content_scripts

正常的配置应该是这样的

"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["content.js"]
  }
]

因为 content.ts 是动态入口，也就是说 content_scripts[0].js 的内容是框架去生成的，而不是我们自己手动填的

这也就造成了 content_scripts 的配置只能是写在 content.ts 这个页面中。这样 Plasmo 才能既知道入口路径，也知道对应的配置

以下示例代码来自： with-content-script/content.ts

// file - content.ts

import type { PlasmoContentScript } from "plasmo"

// 进行 content_scripts 的配置
export const config: PlasmoContentScript = {
  matches: ["https://www.plasmo.com/*"]
}

window.addEventListener("load", () => {
  console.log("content script loaded")

  document.body.style.background = "pink"
})

// 运行后出来的配置可能就是
// "content_scripts": [
//   {
//     "matches": ["https://www.plasmo.com/*"],
//     "js": ["content.[hash].js"]
//   }
// ]

可能又有同学有疑问，就是这样的配置写完，那我岂不是只能写一个 content.ts ? 如果我想一个插件针对不用的站点做不同的操作呢？

好问题，去example找找模版就知道了 example/with-many-content-scripts。这里提供了多个 content.ts 的示例，这样就能针对不同页面注入不同的 content.ts 了

框架也提供了 自定义 manifest.json 的能力。更多的配置可以看官方文档： plasmo customization 这部分

Plasmo 提供的一些库和功能

@plasmohq/storage

参考文档 https://docs.plasmo.com/framework-api/storage

@plasmohq/storage 是一个来自 plasmo 的实用程序库，它抽象了浏览器扩展可用的持久存储 API。当扩展存储 API 不可用时，它会回退到本地存储，允许在弹出窗口 - 选项 - 内容 - 背景之间进行状态同步。

官网还说了一句，如果使用了这个库，配置会自动把 storage 的权限加上

我觉得还是挺好的，这样依赖抹平了不同平台之间存储的差异，也做了保底方案

一些比较特殊的标记符 url: data-text:~ data-base64:~

这部分标记符可以在这些文档中找到 content-scripts、content-scripts-ui、assets

用起来就类似这样的：

import cssText from "data-text:~/contents/plasmo-overlay.css"

import someCoolImage from "data-base64:~assets/some-cool-image.png"

import myJavascriptFile from "url:./path/to/my/file/something.js"

这部分更多的可能是为了相对路径，或者引入一些特殊的内容。比如 data-text:~ 这个就很有用，我可以在 .css 文件中更好的编写我的内容，然后通过 data-text:~ 把文件的内容以 text 引入，用于我注入到页面上

url: 这个也是为了获取这个文件在打包后所处的位置。

比方说我们按正常模式写文件，写完后可能要给 content.js 动态注入到页面去，这时候可以动态创建script标签，
src = chrome.runtime.getURL('xxx.js')

不过因为我们这个是进过了 Plasmo 打包的，有可能对应的资源被加上了hash值，这时候 url: 就是获取文件的路径了（类似 chrome.runtime.getURL(‘xxx.js’) 的功能了）

在示例仓库 examples/with-devtools/devtools.tsx 就有这么一段代码：

import fontPickerHTML from "url:./panels/font-picker/index.html"
import fontPropertiesHTML from "url:./panels/font-properties/index.html"

chrome.devtools.panels.create(
  "Font Picker",
  null,
  // See: https://github.com/PlasmoHQ/plasmo/issues/106#issuecomment-1188539625
  fontPickerHTML.split("/").pop()
)

可以自己打印一下 fontPropertiesHTML 变量，其实是一个网页的路径。（使用.split(“/”)是为了处理一个bug，issuse链接也在备注里了，可以看看了解了解）

文档链接在都贴出来了，更多的用法就自己去摸索了

插件运行和打包

不管是运行 npm run dev 还是 run build，都会生成一个 build/xxxx 目录。里面就是存放着可以运行的chrome插件代码

默认是 chrome-mv3-dev 代表开发 chrome 插件，v3 版本，dev环境

当然你也可以用 --target 指定是开发 firefox 版本/开发 mv2版本, –target-flag 毕竟都不推荐开发 mv2 的东西了。就不细说了

运行 npm run dev 后，把 build/chrome-mv3-dev 这个文件夹拖到浏览器安装插件的位置，就能看到了。不知道怎么操作的建议看下文档： loading-the-extension

build/chrome-mv3-dev 目录下也有 manifest.json 文件，也就是我们在 package.json 里面 + content.ts 的配置，所有的配置都汇总在这里了。想看配置有没有生效看这里就行

插件打包，打包为zip

pnpm build -- --zip
# OR
npm run build -- --zip
# OR
plasmo build --zip

打包到firefox
plasmo build --target=firefox-mv2 --zip

插件在多平台的兼容性问题

build --target=firefox 的作用体现在哪里？

说实话我也没发现，可能是为了多区分开一个目录，或者 firefox 没升级到 mv3 版本，又或者是同样的配置 firefox 有细微差别，Plasmo就可以自动处理掉

至于代码兼容性

在开发过程中，我们都是用 chrome 作为插件API，比如 chrome.runtime.sendMessage

chrome 这个标识各大平台也都识别，比如 360浏览器，包括火狐也兼容 chrome.xxx.xxx 。正常来说不用特别的适配，写的话也按 chrome 来写即可

开头也提到，我因为不能看外网的chrome插件开发文档，好在国内还可以访问 MDN ，API这一块同步的还是比较快的，甚至有些页面有中文翻译了，平时查API可以到这里查

MDN 的文档的API是用的 browser 开头，兼容性可以看对应文档下面的表格。（如果你用browser，在开发过程是没有智能提示的，毕竟我们装的ts包是 @types/chrome）。

也会真的发生有兼容性问题，毕竟chrome更新一直都很快的

用尤大开发的 vue-devtool 插件来看看尤大都是如何处理兼容性问题的（虽然尤大用的不是 Plasmo，不过不影响我们学习代码）

判断运行环境： /packages/shared-utils/src/env.ts

// env.ts 节选代码
export const isBrowser = typeof navigator !== 'undefined'
export const target: any = isBrowser
  ? window
  : typeof global !== 'undefined'
    ? global
    : {}
export const isChrome = typeof target.chrome !== 'undefined' && !!target.chrome.devtools
export const isFirefox = isBrowser && navigator.userAgent.indexOf('Firefox') > -1
export const isWindows = isBrowser && navigator.platform.indexOf('Win') === 0
export const isMac = isBrowser && navigator.platform === 'MacIntel'
export const isLinux = isBrowser && navigator.platform.indexOf('Linux') === 0

根据环境，使用不同的处理方式，比如网页快照

/packages/app-frontend/src/features/timeline/composable/screenshot.ts

chrome V3插件入门到放弃，Plasmo不完全使用指南

在chrome中，能直接使用 chrome.tabs.captureVisibleTab

当然还有随处可见的这样的判断

chrome V3插件入门到放弃，Plasmo不完全使用指南

如果一定要说框架有帮我们处理什么兼容问题，那可能就是本地存储了

提供了 @plasmohq/storage 抹平各个平台的存储api差异，还提供了快捷的方式然我们更新本地存储的内容

处理兼容性问题从来都不是一件容易的事情，搞不好开发人员都处理的很头大，所以更加别指望框架能自动处理。

总的看下来 --target 好像更多是用于发布到不同平台的时候有用，而不是帮我们处理不同浏览器的兼容问题（我的插件不发布到商店去，所以暂时找不到用途）

Plasmo 的介绍就到这里了。我也没开发什么出名的插件（很惭愧）都是处理公司需要的内容，所以可能还有很多好玩的功能没发掘到

Plasmo 还能一键发布到各个平台之类的功能，等着你们自己去探索了

如何应对 MV3 版本中“较大的变动”

一开始介绍的时候有提到版本变动有较小的，还有2个较大的。在我看来较小的变动可能只是改一下配置，不用影响太多业务逻辑代码就能运行的。

而较大的变动就影响挺大的

background 变动的影响

说一个场景，比如我们都很熟悉的浏览器拦截插件，或者其他的插件，下面都有角标。关键是这些角标是根据当前的域名记录的。

chrome V3插件入门到放弃，Plasmo不完全使用指南

怎么做到的呢？依赖 popup 的页面记录吗？
popup 几乎不可能，因为在我开发过程中，popup 在每次打开的时候其实都会重新运行一遍。同一个站点如果打开2次popup.tsx对应的组件就会在执行2次

所以这部分的数据就得留给 background.ts 或者 content.ts 去做

为了搞懂这其中的技巧，我看了一下 猫抓 这个插件的代码

以下代码节选自 猫抓 插件

// js/popup.js
var BG = chrome.extension.getBackgroundPage();
var tabid;
chrome.windows.getCurrent(function(wnd) {
    chrome.tabs.getSelected(wnd.id, function(tab) {
        tabid = tab.id;
        var id = "tabid" + tab.id;
        ShowMedia(BG.mediaurls[id]);
    });
});

// js/background.js

//初始化
if (typeof mediaurls === 'undefined') {
    var mediaurls = new Array();
}

// ...
// 中间的代码用了 chrome.webRequest.onResponseStarted 监听请求
// 然后筛选出 .m3u8 和 分析出对应的 .ts 文件，感兴趣的自己在看看
// ...

//标签更新，清除该标签之前记录
chrome.tabs.onUpdated.addListener(function(tabId, changeInfo) {
    if (changeInfo.status == "loading") //在载入之前清除之前记录
    {
        var id = "tabid" + tabId; //记录当前请求所属标签的id
        if (mediaurls[id])
            mediaurls[id] = [];
    }
});

//标签关闭，清除该标签之前记录
chrome.tabs.onRemoved.addListener(function(tabId) {
    var id = "tabid" + tabId; //记录当前请求所属标签的id
    if (mediaurls[id])
        delete mediaurls[id];
});

可以看到，在 popup.js 里面获取了一个BG

因为 MV2的background是有window对象的。所以 BG 可以理解为 background.html 的 window对象 var BG = chrome.extension.getBackgroundPage();

从 window 对象中获取 mediaurls 参数，获取对应tab要显示的角标数，然后给到 popup 显示

如果 background 变成了一个 Service Worker ，那就不存在 window 对象了

解决方案就是改用通信的方式，popup发起一个sendMessage。background来监听，并且进行回调给popup
整体的思路还是用 background 来存储和转发消息，background 收到的内容后存储到本地去。

【非常严重】网络请求拦截的变动 declarativeNetRequest

只能感叹一句，V2 版本的拦截请求还是很好用的。

推荐一篇教程：小茗同学: 【干货】Chrome插件(扩展)开发全攻略这里面的的攻略很多都没过时，除了上面说的改动其他都很值得参考学习。我也是看这个入的门

可以看到教程的 8.6. webRequest 看看v2版本的拦截网络请求写法

之前是通过声明 webRequest 、 webRequestBlocking 等权限来进行网络请求的拦截。不过现在声明了也没用了 issues/1163

都要改为 declarativeNetRequest 来拦截

虽然新版的API也能拦截请求，修改head头之类的操作
但是，这些操作都没有回调！！（V2版本是有回调的，猫抓就是基于回调才抓的请求地址）

不过进过一通瞎找，找到另外一个文档（MDN还没更新 declarativeNetRequest 的内容）

onRuleMatchedDebug

chrome V3插件入门到放弃，Plasmo不完全使用指南

这个方法有这么一段话

Fired when a rule is matched with a request. Only available for unpacked extensions with the declarativeNetRequestFeedback permission as this is intended to be used for debugging purposes only.

当规则与请求匹配时触发。仅适用于具有 declarativeNetRequestFeedback 权限的解压扩展，因为这仅用于调试目的。

注意是 解压扩展，意思就是必须是解压的包/zip包，并且声明了这个权限才能用。
如果你的插件是想发布到应用市场，或者生成 .crx 后缀的插件包，一样是用不了 onRuleMatchedDebug 滴（累了）

虽然background不能直接监听返回的内容，不过 devtool 面板可以啊 devtools/network。但是如果你想用devtool面板的API话，你得打开F12才能用（累了*2）

所以目前拦截回调的这一块还没有想出非常通用的方案，或许这就是chrome口中的安全，隐私…

如果想粗暴点解决的话其实可以把要拦截的源文件下载下来，然后手动添加一个 window.postMessage(xxx) 主动给 content.ts 发消息，然后 content.ts 在转发到后台去
background 部分就拦截网络请求，redirect 到插件下载的源文件那边去（其实就是针对性很强针对某个网页的某个js可以这么搞）

如果是想篡改某些js的内容，而且自己会本地开一个服务的话，用 redirect 真的是很方便的

既然都讲到拦截了，顺便讲讲 如何拦截网页发出的请求。原理就是用 content.js 注入js，修改 window.XMLHttpRequest 和 window.fetch 方法就能拦截到了

推荐直接学习： YGYOOO/ajax-interceptor 这里面的代码

唯一的问题可能就是 content.js 注入的速度没有页面发起请求的快，就会有几条漏网之鱼。

最后

这篇文章主要还是想介绍下 Plasmo。个人感觉用下来还是挺好用的

至于chrome 插件要升级到 MV3 最严重的其实还是网络请求相关的。其余的应该都还好（最起码有解决方案）

讲了那么多其实没有讲到一些开发的技巧类东西，主要是一些需要注意的坑。所以汇总一下链接方便查找学习

文档类

chrome原汁原味文档：https://developer.chrome.com/docs/extensions/mv3/）
MDN文档插件开发文档：https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
热心网友同步的原文文档（MDN找不到的时候就来这里看看）：https://sunnyzhou-1024.github.io/chrome-extension-docs/extensions/api_index.html

入门教程推荐

小茗同学【干货】Chrome插件(扩展)开发全攻略 (http://blog.haoji.me/chrome-plugin-develop.html)[http://blog.haoji.me/chrome-plugin-develop.html]

插个题外话，如果你既没有魔法，又想看原汁原味文档（挺好的，很有追求）

可以上 github https://github.com/GoogleChrome/developer.chrome.com

把整个 developer.chrome.com 搞下来（下面的命令不用我细说了把）

# 安装依赖的
npm run ci

# dev 后 打开 http://localhost:8080/ 就可以看到
npm run dev

# 如果你想同步一份到自己服务器，就运行把
npm run production && npm start

插件开发介绍就到这了，如果你有好的插件记得也推荐给我文章来源地址https://www.toymoban.com/news/detail-480910.html

到了这里，关于chrome V3插件入门到放弃，Plasmo不完全使用指南的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！

chrome V3插件入门到放弃，Plasmo不完全使用指南