如何用React或Vue高效开发浏览器插件并享受热更新？

浏览器扩展开发的完整快速上手指南

1. 创建项目并安装依赖

首先使用 Vite 创建基于 React 与 TypeScript 的项目，并安装适配浏览器扩展的构建插件。

npm create vite@latest my-chrome-extension -- --template react-ts
cd my-chrome-extension
npm install @crxjs/vite-plugin@beta -D

2. 配置 Vite (vite.config.ts)

在配置文件中集成 React 插件与 CRXJS 插件，以支持浏览器扩展的构建流程。

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { crx } from '@crxjs/vite-plugin'
import manifest from './manifest.json'

export default defineConfig({
  plugins: [react(), crx({ manifest })],
})

3. 创建扩展清单 (manifest.json)

清单文件定义扩展的基本信息、权限及核心资源路径，需遵循 Manifest V3 规范。

{
  "manifest_version": 3,
  "name": "示例Chrome扩展",
  "version": "1.0.0",
  "action": {
    "default_popup": "index.html"
  },
  "background": {
    "service_worker": "src/background/index.ts",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["src/content/index.ts"]
    }
  ],
  "permissions": ["storage"]
}

4. 创建扩展文件结构

合理的目录结构有助于维护扩展的不同功能模块。

my-chrome-extension/
├── src/
│   ├── background/
│   │   └── index.ts
│   ├── content/
│   │   └── index.ts
│   ├── App.tsx
│   └── main.tsx
├── index.html
├── manifest.json
└── vite.config.ts

5. 运行开发服务器

npm run dev

执行后 Vite 会在根目录生成 dist 文件夹，内含可加载的扩展文件。

6. 加载扩展到浏览器

1. 访问 chrome://extensions/。

2. 启用右上角 开发者模式。

3. 点击 加载已解压的扩展程序。

4. 选择项目中的 dist 文件夹。

核心开发优势详解

1. 热更新（HMR）：修改弹出页或选项页可即时生效；内容脚本变更会触发对应标签页刷新；后台脚本变更会使扩展自动重载。

2. 完整的类型支持：安装 Chrome API 类型定义以获得完善的智能提示与编译期检查。

   npm install @types/chrome -D

   chrome.storage.local.set({ key: 'value' })
   chrome.runtime.sendMessage({ type: 'greeting' })

3. 现代化的前端开发体验：支持 JSX/TSX、Vue 单文件组件、CSS Modules、Sass、Less、环境变量及 ES 模块。

实际开发技巧示例

在内容脚本中嵌入 React 组件：

import { createRoot } from 'react-dom/client'
import App from '../App'

const container = document.createElement('div')
container.id = 'my-extension-root'
document.body.appendChild(container)

const root = createRoot(container)
root.render()

在后台脚本中使用模块化编程：

import { initializeApp } from './services/app'

chrome.runtime.onInstalled.addListener(() => {
  console.log('扩展已安装')
  initializeApp()
})

重要注意事项

1. 本方案基于 Manifest V3 规范。

2. 不支持服务端渲染（SSR）。

3. 执行 npm run build 可生成用于发布的正式包。

4. 多页面扩展需在项目中增加对应 HTML 入口并在清单中声明。

总结

@crxjs/vite-plugin 将现代前端工程化能力引入浏览器扩展开发，显著改善传统流程中的重复操作与类型安全问题：

• 热更新减少手动刷新成本。

• 类型系统提升代码可靠性与开发效率。

• 无缝兼容主流框架与工具链。

适用于基于 React、Vue 或 Svelte 构建高质量浏览器扩展的开发场景。

ReactVue