如何使用chrome-extension-boilerplate-react-vite 从零开始开发一款浏览器插件

码觉客
3 阅读7分钟

下面是从零开始使用 Jonghakseo/chrome-extension-boilerplate-react-vite 这个项目模板来开发浏览器插件的详细步骤。这个模板提供了一个基于 React, TypeScript 和 Vite 的现代化开发环境。

前提条件:

  1. Node.js 和 npm/yarn/pnpm: 确保你的系统安装了 Node.js (推荐 LTS 版本) 和对应的包管理器。
  2. Git: 你需要 Git 来克隆模板仓库。
  3. 代码编辑器: 如 VS Code。
  4. 目标浏览器: Google Chrome 或 Microsoft Edge (或其他支持 Manifest V3 的 Chromium 浏览器)。
  5. 基础 Web 开发知识: 了解 HTML, CSS, JavaScript, React 和 TypeScript。

步骤 1: 获取模板并安装依赖

  1. 克隆仓库: 打开你的终端，使用 Git 克隆该模板仓库。

    git clone https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite.git my-react-vite-extension

    将 my-react-vite-extension 替换为你想要的项目名称。

  2. 进入项目目录:

    cd my-react-vite-extension

  3. 安装依赖: 使用你选择的包管理器安装项目所需的依赖项。

    # 使用 npm
npm install

# 或者使用 yarn
# yarn install

# 或者使用 pnpm
# pnpm install

步骤 2: 理解项目结构

花点时间熟悉一下这个模板的项目结构，通常会类似这样：

  • public/: 存放静态资源，会被复制到构建输出目录（dist）的根目录。
    • manifest.json: 核心文件！ 这是浏览器扩展的清单文件，你需要在这里定义插件的名称、版本、权限、入口点等。在这个模板中，你需要手动编辑和维护这个文件。
    • _locales/: (可选) 用于国际化。
    • assets/: 可能包含图标等资源。
  • src/: 存放主要的源代码。
    • pages/: 包含不同类型页面的代码。
      • popup/: 弹出窗口的代码 (通常包含 index.html, main.tsx, Popup.tsx 等)。
      • options/: 选项页面的代码 (类似结构)。
      • content/: 内容脚本的代码 (通常包含 index.ts 或 ui.tsx 如果有界面)。
      • background/: 后台脚本 (Service Worker) 的代码 (通常是 index.ts)。
    • components/: 可复用的 React 组件。
    • assets/: 其他源代码中使用的资源（如图标）。
    • hooks/: 自定义 React Hooks。
    • utils/: 工具函数。
  • vite.config.ts: Vite 的配置文件。这个模板已经预先配置好了构建扩展所需的基本设置。
  • package.json: 项目信息、脚本命令和依赖列表。
  • tsconfig.json: TypeScript 配置文件。
  • README.md: 重要！ 仔细阅读模板自带的 README 文件，它可能包含该模板特定的设置说明和使用技巧。

步骤 3: 配置 manifest.json

打开 public/manifest.json 文件。这是你需要手动配置的关键部分。根据你的插件需求进行修改：

{
  "manifest_version": 3,
  "name": "My React Vite Extension", // 修改为你的插件名称
  "version": "1.0.0", // 修改版本号
  "description": "A browser extension built with React, Vite, and TypeScript.", // 修改描述
  "options_page": "src/pages/options/index.html", // 指向选项页 HTML (如果需要)
  "background": {
    "service_worker": "src/pages/background/index.js", // 指向后台脚本 JS 输出 (注意 Vite 构建后的路径)
    "type": "module"
  },
  "action": {
    "default_popup": "src/pages/popup/index.html", // 指向 Popup 页 HTML
    "default_icon": "assets/icon-34.png" // 修改为你的图标路径
  },
  "icons": {
    "128": "assets/icon-128.png" // 修改为你的图标路径
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"], // 修改为你需要注入脚本的 URL 模式
      "js": ["src/pages/content/index.js"], // 指向内容脚本 JS 输出 (注意 Vite 构建后的路径)
      // "css": ["contentStyle.css"] // 如果需要注入 CSS (Vite 通常会将 CSS 打包进 JS)
    }
  ],
  "web_accessible_resources": [ // 如果内容脚本需要访问打包后的资源 (如图标、字体、或 UI chunk)
    {
      "resources": [
        "assets/icon-128.png",
        "assets/icon-34.png",
        "src/pages/content/index.css", // 如果内容脚本的 CSS 被分离
        "src/pages/contentUI/index.js" // 如果内容脚本 UI 是动态加载的
      ],
      "matches": ["*://*/*"] // 限制可以访问这些资源的域名
    }
  ],
  "permissions": [ // **重要：按需添加权限**
    "storage", // 示例：允许使用 chrome.storage
    "activeTab" // 示例：允许临时访问活动标签页
    // "tabs",
    // "scripting" // 如果需要通过 API 注入脚本或 CSS
  ],
   "host_permissions": [ // **重要：按需添加主机权限 (MV3 必须)**
    // "<all_urls>", // 谨慎使用
    "*://*.google.com/*" // 示例
  ]
}

注意:

  • 路径问题: manifest.json 中的路径（特别是 js 和 css 字段）需要指向 Vite 构建后在 dist 目录中的文件路径。Vite 的配置通常会处理好入口点，但你需要确保这些路径是正确的。阅读模板的 README 或检查构建输出来确认。
  • 图标: 确保 manifest.json 中指定的图标文件实际存在于 public/assets 或 src/assets (取决于模板配置)。
  • 权限: 仔细考虑并只申请你的插件确实需要的权限。

步骤 4: 开发插件功能

现在你可以开始编写代码了：

  1. Popup:

    • 编辑 src/pages/popup/ 目录下的文件 (Popup.tsx, main.tsx 等)。
    • 像开发普通 React 应用一样构建你的弹出窗口界面。
    • 可以在组件中调用 chrome.* API (如 chrome.tabs.query, chrome.storage.local.get) 来与浏览器交互。

  2. Content Script:

    • 编辑 src/pages/content/ 目录下的文件 (例如 index.ts)。
    • 在这里编写操作网页 DOM、读取页面信息或向页面注入 UI 的代码。
    • 如果需要在页面上渲染 React UI，你可能需要创建一个根元素并使用 ReactDOM.createRoot().render(...)。
    • CSS 注入: 通常，在内容脚本的 index.ts 或对应的 UI 组件中直接 import './style.css'，Vite 会处理 CSS 的打包和注入（可能通过 JS 动态插入 <style> 标签）。确保 web_accessible_resources 允许访问这些 CSS 文件（如果它们被分离出来）。

  3. Background Script (Service Worker):

    • 编辑 src/pages/background/index.ts。
    • 添加事件监听器，如 chrome.runtime.onInstalled, chrome.action.onClicked, chrome.tabs.onUpdated, chrome.runtime.onMessage 等。
    • 记住 Service Worker 的生命周期特性，使用 chrome.storage 来持久化状态。

  4. Options Page:

    • 编辑 src/pages/options/ 目录下的文件。
    • 构建设置界面，通常使用 chrome.storage 来保存和加载用户设置。

步骤 5: 运行和调试

  1. 启动开发服务器:

    npm run dev
# or yarn dev / pnpm dev

    Vite 会启动开发服务器，并进行初始构建。它会监听文件变化并尝试进行热模块替换 (HMR)。构建输出通常在 dist 目录。

  2. 加载插件到浏览器:

    • 打开 Chrome/Edge。
    • 地址栏输入 chrome://extensions 或 edge://extensions。
    • 打开右上角的 “开发者模式” 开关。
    • 点击 “加载已解压的扩展程序” 按钮。
    • 选择项目的 dist 文件夹 (这是 Vite 开发模式的构建输出目录)。
    • 插件图标应出现在工具栏。

  3. 调试:

    • Popup: 右键点击工具栏图标 -> “检查弹出式窗口”。
    • Content Script: 打开匹配 manifest.json 中 matches 规则的网页 -> 按 F12 打开开发者工具 -> Console 或 Sources -> Content scripts。
    • Background Script: chrome://extensions 页面 -> 找到插件 -> 点击 “服务工作进程” (Service Worker) 链接。
    • Options Page: chrome://extensions 页面 -> 找到插件 -> 点击“详细信息” -> “扩展程序选项” -> 按 F12 打开开发者工具。
    • HMR: Vite 的 HMR 对 Popup 和 Options 页面效果最好。对于 Content Script，修改后有时可能需要手动刷新目标网页或扩展。对于 Background Script，修改后通常需要手动刷新扩展 (在 chrome://extensions 页面点击刷新按钮)。

步骤 6: 构建生产版本

完成开发后，创建用于发布的优化版本：

npm run build
# or yarn build / pnpm build

这会在 dist 目录中生成生产环境的代码。

步骤 7: 打包发布

  1. 进入 dist 目录。
  2. 将 dist 目录的所有内容（而不是 dist 目录本身）压缩成一个 .zip 文件。
  3. 将这个 .zip 文件提交到 Chrome Web Store 或其他分发平台。

总结 (Jonghakseo Boilerplate 特点):

  • 优点:
    • 提供了一个现代化的 React + TS + Vite 开发环境。
    • 结构清晰，适合熟悉 React 生态的开发者。
    • 预配置了 Vite 用于扩展开发的基本设置。
  • 缺点:
    • 需要手动管理 manifest.json: 这是与 CRXJS 等工具的主要区别，需要开发者自己处理路径、权限和各种配置细节，更容易出错。
    • HMR 体验可能不如专用工具: 特别是内容脚本和后台脚本的 HMR 可能需要更多手动干预。

按照这些步骤，你应该能够使用 Jonghakseo 模板成功开发你的浏览器插件了。记得经常查阅模板的 README.md 和 Vite、React、Chrome Extension 的官方文档。

文章告一段落。如果你意犹未尽，渴望持续提升技术实力、拓宽视野，欢迎关注同名微信公众号“码觉客”。我们致力于分享高质量的技术干货、实战经验和前沿资讯，助你在技术的道路上走得更远。即刻搜索关注，解锁更多精彩！

avatar
文章
阅读
粉丝