快速上手

准备环境

Node.js >= 16，推荐使用 Node LTS 版本。

自动安装

推荐使用 web-extend 工具自动创建项目。在命令行界面运行命令：

npx web-extend@latest init

web-extend 内置了以下模板。这些模板都使用 TypeScript，如果需要使用 JavaScript，可以在生成项目后手动将 .ts 文件后缀名改为 .js。

• Vanilla
• React
• Vue
• Svelte

WebExtend 兼容任何前端框架，如需在其他框架中使用，请参考手动安装的部分。

手动安装

安装依赖项

创建项目并安装依赖项。WebExtend 使用 Rsbuild 作为底层构建工具，因此还需要安装它和一个 @web-extend/rsbuild-plugin 插件。

npm

mkdir my-extension-app
cd my-extension-app

npm init -y
npm add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

pnpm

mkdir my-extension-app
cd my-extension-app

npm init -y
pnpm add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

yarn

mkdir my-extension-app
cd my-extension-app

npm init -y
yarn add -D web-extend @rsbuild/core @web-extend/rsbuild-plugin

推荐安装 TypeScript、React/Vue、Eslint/Prettier/Biome 等前端工具，提升开发体验（可选）。

添加脚本命令

修改 package.json，添加 "type": "module" 字段及如下命令：

package.json

{
  "type": "module",
  "scripts": {
    "dev": "web-extend rsbuild:dev --open",
    "build": "web-extend rsbuild:build",
    "preview": "web-extend preview",
    "zip": "web-extend zip"
  }
}

上述命令的含义如下：

• dev: 使用 Rsbuild 在开发环境构建扩展，同时打开浏览器运行扩展。
• build: 使用 Rsbuild 构建生产版本的扩展。
• preview: 预览生产版本的扩展。需要先执行 build 命令。
• zip: 将生产版本的扩展压缩为一个 .zip 文件，以备发布。需要先执行 build 命令。

其中，在浏览器中运行扩展的功能基于 web-ext 工具实现。如果要使用这项功能，请在项目中额外安装该工具。

npm

npm add -D web-ext

pnpm

pnpm add -D web-ext

yarn

yarn add -D web-ext

添加 Rsbuild 配置

创建 rsbuild.config.ts，添加如下内容。

rsbuild.config.ts

import { defineConfig } from "@rsbuild/core";
import { pluginWebExtend } from "@web-extend/rsbuild-plugin";

export default defineConfig({
  plugins: [pluginWebExtend()],
});

添加入口文件

创建 src 源码目录，并创建 popup.js 文件，文件内容如下。WebExtend 将基于文件系统自动解析入口。

src/popup.js

const rootEl = document.querySelector("#root");
if (rootEl) {
  rootEl.innerHTML = `
  <div class="content">
    <h1>Vanilla WebExtend</h1>
    <p>This is a popup page.</p>
  </div>
  `;
}

web-extend 工具提供了自动生成入口文件的功能，也可以使用它来添加入口文件，运行命令。

npx web-extend generate popup

添加额外的 manifest.json 配置项，比如 name 、permissions 等。（可选）

rsbuild.config.ts

import { defineConfig } from "@rsbuild/core";
import { pluginWebExtend } from "@web-extend/rsbuild-plugin";

export default defineConfig({
  plugins: [pluginWebExtend({
    manifest: {...} 
  })],
});

运行和构建

• 执行 npm run dev 命令，启动服务器，自动打开浏览器并运行扩展。
• 执行 npm run build 命令，构建生产版本的扩展。

如果需要手动加载扩展，请移除 dev 命令中的 --open 选项，在浏览器扩展页面开启开发者模式，加载 dist/chrome-mv3-dev 或 dist/chrome-mv3-prod 目录。

发布

执行 npm run zip 命令压缩生产版本的扩展，在浏览器的应用商店进行发布。

• Chrome Docs
• Firefox Docs
• Safari Docs
• Microsoft Docs