下一代浏览器插件开发框架 WXT 入门指南

前言

如果你没有开发过浏览器插件，那么我建议你直接选择一款框架去开发，因为我们在开发一款 Chrome 插件时，是采用 HTML、CSS 和 JavaScript 的传统方式开发，无法直接使用 vue、react 等常用框架去编写 UI，编译环境也需要自己手动去搭建，往往一些简单的插件，光是环境搭建比业务开发时间还要长。

今天介绍的 WXT 是一个免费的开源浏览器插件开发框架，它致力于为开发者带来最好的开发体验和最快的开发速度，学习它可以为你的插件搭建一个坚实的基础，并为你节省大量的基础建设时间。

特性

• 支持所有浏览器，包括 Chrome、Firefox、Edge、Safari 和一切基于 Chromium 的浏览器。
• 一套代码支持 Manifest V2 和 V3 的插件。
• 支持 HMR，更新内容不再需要重新加载整个插件。
• 入口点，manifest.json 是根据入口点的文件生成。
• 默认使用 typescript。
• 自动导入，与 Nuxt 一样的自动导入功能，默认的接口无需导入即可使用。
• 自动下载远程代码，Google Manifest V3 要求拓展程序不依赖远程代码。
• 轻松使用任何带有 vite 插件的前端框架。
• 内置包分析工具，方便优化，最小化扩展应用。

官方提供了多个快速入门模板，方便生成你习惯的技术方案。
未来还会推出自动压缩、上传、发布。

对比

有经验的开发者，一定了解过另一款框架，Plasmo，截止文章编写日期，它已经有 7.7k star，对比 WXT 不足 500 star 可谓是遥遥领先。那么本章节来说明一下为什么我们要选择 WXT?

Plasmo 不足之处

Plasmo 支持很多 WXT 的特性

• 仅 React、Vue 和 Svelte，如果有其他框架使用者局限性就比较大了。
• 不支持自动打开浏览器并安装，这步操作比较繁琐，极大的拉低了开发体验。
• HMR 目前仅支持 React，那么像我们使用其他框架的开发者，同样拉低了开发体验，并且更新内容时还会重新加载整个插件。

WXT 不足之处

• 未支持自动化发布。
• 未支持消息传递。

当然这些官方正在努力更新中，这两条对于开发体验影响不大，相信不久的将来就会把这些特性添加上去。

前置知识

如果你没有浏览器插件开发经验，这里提供了几个需要了解的名词含义，如果你已经了解，可以直接跳过本章节。

Manifest

Manifest(manifest.json) 是一个配置文件，包含插件的基础信息和功能。如果你不使用框架去开发，你需要了解一下。

⚠️ 使用 WXT 开发，可以忽略这一步，因为他会在构建时自动生成，Manifest V2 和 V3 是指 Chrome 扩展的清单文件的不同版本。

Manifest V2

V2 是旧版本清单文件格式。它是基于JSON格式的配置文件，用于描述扩展的名称、版本、权限、图标、页面注入等信息。Manifest V2提供了一些基本的功能和API，如页面操作、消息传递和存储管理等。它是较早版本的Chrome扩展清单文件格式，目前仍然被广泛使用。

Manifest V3

V3 是新版本清单文件格式。它在 V2 的基础上进行了一些重大的改进和更新，引入了一些新的概念和API，如声明式的事件页、强制性的权限声明、更严格的内容脚本规则等。提高了扩展的性能、安全性和可维护性。

入口文件

在开发 Chrome 插件时，有4个入口文件，他们分别是：

• background.js
• content.js
• injected.js
• popup.html

service_worker

浏览器插件是基于事件的程序，事件是浏览器触发器，例如导航到新网页、移除书签或关闭标签页。我们可以在 service_worker 文件中监听这些后台的事件，然后做出响应。

content_scripts

content.js 的意思是内容脚本，运行于网页环境，使用标准文档对象模型 (DOM)，通过它我们就可以获取或修改网页上的内容，这与平时开发网页的方式一致，在此基础上，还可以访问一些其他的 API，主要是与插件的其他部分通讯的接口，它并不支持全部的 API。

injected.js

可以注入 JavaScript 脚本到网页环境，注意这个是注入到整个网页中，content_scripts 只是特定的页面。

popup.html

弹窗，是一个非常常见的场景，当用户点击某个扩展程序的操作时，该扩展程序会显示一个弹出式窗口，用 popup.html 来写这个弹窗的 UI。

安装

看的多不如实际操作一下，所以我们从创建一个模板开始学习。

执行命令：

npx wxt@latest init <project-name>

或者你安装了 pnpm：

pnpx wxt@latest init <project-name>

⚠️ 这里建议使用 node(v18+)。

脚本下载后会出现选择起始模板的选项，根据你喜欢的框架选择即可。

进入项目路径，安装依赖，虽然运行 npm run dev 即可自动打开浏览器并看到插件已经安装可用了。

这里我使用的 vue 模板。

目录结构

看一下目录结构：

• .output/ 构建的结果目录。
• .vscode/ 和 .wxt 目录都是一些配置和类型，无需了解。
• assets/ 可以存放资源，存储构建过程中将被 vite 处理。
• public/ 同样的资源目录，会被原样复制到输出目录。
• components/ 是存放 vue 通用组件的目录，这个大家都很熟悉了。
• entrypoints/ 是最核心的路径，所有业务源码都在这里编写。
• package.json 如果未配置 manifest，那么插件 name 和 version 将会在这里取。
• wxt.config.ts 最重要的配置文件，任何行为都需要在这里配置。

配置

首先打开 wxt.config.ts 发现里面有 vite 的配置，这代表着，不论你使用什么框架，都构建于 vite，这也是为什么带有 vite 插件的框架就可以在 WXT 中使用的原因。

WXT 提供了 defineConfig 方法，携带完全的 ts 类型说明，可以更加方便的去配置。这里我们讲几个比较重要的配置项：

目录配置

⚠️ 本节建议直接跳过。

如果官方提供的目录结构不是你喜欢的，你可以自行修改，但我不建议你这么做。

• root 项目的根目录，默认值：process.cwd()。
• srcDir 所有源代码的位置，默认值：rootDir。
• entrypointsDir 包含所有入口点的文件夹，默认值 <srcDir>/entrypoints。
• publicDir 公共资源的文件夹，默认值： <srcDir>/public。

vite

模板已经生成了 vue 的配置，如果你想改为 react，或者移植过来的项目，可以这样配置：

import { defineConfig } from 'wxt';
import react from '@vitejs/plugin-react';

export default defineConfig({
  vite: () => ({
    plugins: [react()],
  }),
});

当然 vite 的其他配置也在这里。

manifest

虽然 manifest 是根据源码自动生成，但是也可以自定义配置，直接在 wxt.config.ts 中的 manifest 字段中配置即可。

⚠️ permissions 配置是很重要的，不配置是没有权限使用的。

manifestVersion

可以明确规定 manifest 的版本，他的值为 2 或者 3，命令行 --mv2 或 --mv3 可以覆盖此选项。

⚠️ manifest v2 版本已经无法上架谷歌商店，这点值得注意。

browser

明确要构建的浏览器，他的值是任意字符串，默认是 chrome，常用的还有 firefox、edge、safari。

---

其他的配置项请参考配置文档。

入口点

在 WXT 中，入口点是通过将文件添加到 entrypoints/ 目录来定义的，也就是约定优于配置。通常一个目录下应该有这几个文件：

<rootDir>
└─ entrypoints/
   ├─ background.ts
   ├─ content.ts
   ├─ injected.ts
   └─ popup.html

manifest.json 也会根据这个目录生成相应的配置：

{
  "manifest_version": 3,
  "action": {
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [
    {
      "js": ["content-scripts/content.js"]
    }
  ]
}

background、content、popup 是 WXT 自动识别的特殊名称，他们才会自动被加入到 manifest 中，其他的文件也会被构建到插件中，但不会在 manifest 中定义，例如 injected.ts 会被输出到 .output/**/injected.js，这类文件一般都通过 browser.runtime.getURL("/injected.js") 的方式访问。

自动被识别的文件比较多，这里可以参考Entrypoints文档。

扩展接口

WXT 构建在 webextension-polyfill(Mozilla 出品) 之上，它使用标准 browser 全局变量，做过 chrome 插件的同学应该知道，全局变量是 chrome，直接理解将 chrome 替换为 browser 即可，因为 WXT 不止是为了 Chrome 做插件。另外一定是该死的回调终于可以使用 async/await 代替了。

由于支持自动导入，所以我们无需 import { browser } from 'wxt/browser'，这里我们利用一个小 demo 了解一下他的用法，通过 onInstall 监听到插件被安装的事件，这时我们通过本地存储将事件保存下来：

// background.ts
export default defineBackground(() => {
  browser.runtime.onInstall.addEventListener(({ reason }) => {
    if (reason === 'install') {
      browser.storage.local.setItem({ installDate: Date.now() });
    }
  });
});

⚠️ 注意 storage 需要添加到 manifest.permissions 中。

存储

上面的例子提到了将安装事件保存到本地存储，WXT 还提供了更精简的 API 用于存储：

import { storage } from 'wxt/storage'; // 无需引用

await storage.getItem('local:installDate');

所有存储键都必须以其存储区域为前缀，支持 local:、session:、sync:、managed:。

监听存储变化

如果要对某个键单独设置监听，可以通过使用 storage.watch:

const unwatch = storage.watch<number>('local:counter', (newCount, oldCount) => {
  // ...
});

unwatch(); // 取消监听

对象存储

同样也支持键值对的存储方式，使用 storage.setMeta 和 storage.getMeta:

await storage.setMeta('local:preference', { v: 2 });
await storage.getMeta('local:preference');

删除可以通过 storage.removeMeta:

await storage.removeMeta('local:preference');
await storage.removeMeta('local:preference', 'lastModified');
await storage.removeMeta('local:preference', ['lastModified', 'v']);

注意他们都是异步的。

Content Script UI

上文提到 Content Script 可以操作页面 DOM，这意味着我们可以随意修改某个页面的 UI。这里举个例子，我个人安装了 V2EX 的某个插件，看一下使用插件后的前后对比：

使用前：

使用后：

可见界面已经天差地别，并且评论区的功能也变了，回复的评论改在了相应评论的后面，这就是插件带来的便利。

三种实现方式

与 popup 不同，Content Script UI 的实现方式比较复杂，所以 WXT 提供了三种模式去创建内容脚本 UI，极大的降低了开发成本：

方法	样式隔离	事件隔离	HMR	使用页面上下文
Integrated	❌ 合并	❌	❌	✅
Shadow Root	✅	✅ 默认关闭	❌	✅
IFrame	✅	✅	✅	❌

他们都拥有各自的特性，需要按使用场景来使用。

Integrated

这种方式是将脚本和样式一块注入，这意味着页面上的内容和脚本 UI 内容互相是产生影响的。

建议期望内容脚本 UI 与页面风格一致时使用。

vue 示例：

import { createApp } from 'vue';
import App from './App.vue';

export default defineContentScript({
  matches: ['<all_urls>'],
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
      anchor: '#anchor',
      onMount: (container) => {
        const app = createApp(App);
        app.mount(container);
        return app;
      },
      onRemove: (app) => {
        app.unmount();
      },
    });
    ui.mount();
  },
});

示例中使用了 createIntegratedUi 方法创建 UI，这里说明一下几个参数的含义：

• matches 匹配对应的 URL 去注入（不论哪种方式都需要填这个参数）。
• anchor 是一个 CSS 选择器或函数，也就是将 UI 插入到页面的哪个位置。
• 其他的就是一些事件了，创建和销毁，更多请参考文档。
• position 表示注入方式，可选值有 inline、overlay、modal。

Shadow Root

如果你不想 CSS 互相影响，那么你可以选择这种模式。

import './style.css'; // 注意要引入 CSS
import { createApp } from 'vue';
import App from './App.vue';

export default defineContentScript({
  matches: ['<all_urls>'],
  cssInjectionMode: 'ui', // 注入模式
  async main(ctx) {
    const ui = await createShadowRootUi(ctx, {
      // 与上一个例子一致
    });
    ui.mount();
  },
});

参数 cssInjectionMode 是 CSS 注入模式的配置，它有3个可选参数：

• ui 从 manifest 排除 CSS，在调用 createShadowRootUi 时将 CSS 添加到 UI。
• manifest 使用 manifest CSS 下的样式。
• manual 从 manifest 排除 CSS，使用 browser.runtime.getURL 获取 CSS。

IFrame

大家对它都很熟悉了，很多微前端框架都支持这种形式，因为它天生就对 CSS 和脚本隔离。

WXT 提供了一个辅助函数 createIframeUi，用来加载一个 HTML 页面：

export default defineContentScript({
  matches: ['<all_urls>'],
  async main(ctx) {
    const ui = await createIframeUi(ctx, {
      page: '/example-iframe.html',
      // 其他配置一致
    });
    ui.mount();
  },
});

我个人不太喜欢这种模式，他唯一的优点是支持 HMR。

远程代码

Google 对 Manifest V3 要求不能依赖远程代码，我们在使用谷歌分析这类工具时，可以采用这样的方式：

import 'url:https://www.googletagmanager.com/gtag/js?id=G-XXXXXX';

import + url: 的形式，WXT 会自动下载远程代码到本地。

构建

运行 npm run build 即可，默认构建了 Chrome 插件。

如果运行 npm run build:firefox，则会构建 Firefox 插件，可以看到打包使用的 manifest v2：

这时默认打包的浏览器对应 Manifest 版本：

浏览器	默认 Manifest 版本
chrome	3
firefox	2
safari	2
edge	3
其他任何浏览器	3

如果你想打包 Firefox 时使用 v3 版本，可以在命令后增加 --mv3 参数即可。

构建 zip

如果你是第一次向商店发布插件，需要先了解一下上传步骤，每个商店都需要上传 .zip 文件。

庆幸的是 WXT 也提供了指令去做：

wxt zip
wxt zip -b firefox

执行后 .zip 文件会出现在 .output。

我爱掘金插件实战

接下来通过一个简单的例子：我爱掘金插件实战，来将 popup、background、content 三个东西串起来实践一下。有兴趣可以参考代码仓库。

实现效果，每隔1秒钟爱掘金一次，将页面上所有 .title 元素都替换成我爱掘金*次，弹窗也同样展示，数据存储在 storage，刷新页面也不会让爱消失。

效果展示：

配置

首先先配置一下 package.json 的 name 和 description，这步不重要。

然后 wxt.config.ts 配置一下 manifest.permissions:

export default defineConfig({
  manifest: {
    permissions: ["storage"],
  },
});

因为我们要存储爱了掘金多少次，所以要在这里获得存储权限。

定时加爱

每秒增加一次爱的话，我们可以在 background.ts 中去做。为什么不是在 content.ts 中呢？因为我们要替换页面上的元素时，如果存在多个的话，那么我们每秒就会爱掘金 N 次了。当然在 popup 里去写也没什么问题，但是我建议 popup 仅写 UI，不要涉及业务逻辑。

// background.ts
export default defineBackground(() => {
  const count = storage.defineItem<number>("local:count", {
    defaultValue: 0,
  });

  setInterval(async () => {
    const _count = await count.getValue();
    console.log(_count);
    storage.setItem("local:count", _count + 1);
  }, 1000);
});

弹窗展示

模板已经生成了 popup/App.vue，我们直接修改这个文件即可：

<!-- popup/App.vue -->
<template>
  <div>
    我爱掘金{{ count }}次
  </div>
</template>

<script lang="ts" setup>
import { onMounted, ref } from 'vue';

const count = ref(0);

onMounted(() => {
  setInterval(async () => {
    count.value = await storage.getItem<number>('local:count') || 0;
  }, 1000);
});
</script>

让页面充满爱掘金

Content Script 前面讲了不少，大家应该是轻车熟路。

import { createApp } from "vue";
import LoveJuejin from "@/components/LoveJuejin.vue";

export default defineContentScript({
  matches: ["<all_urls>"],
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: "inline",
      anchor: "#juejin",
      onMount: (container) => {
        const app = createApp(LoveJuejin);
        app.mount(container);
        return app;
      },
      onRemove: (app) => {
        if (app) {
          app.unmount();
        }
      },
    });
    ui.mount();
  },
});

至此结束，运行一下体验吧。

参考

• Chrome 插件开发文档
• WXT 文档
• WXT 配置文档。
• WXT Entrypoints 文档。