使用Vite + React + Node 从0到1落地一款Chrome插件

逃离IDE
65 阅读3分钟

Chrome Side Panel Extension

基于 React + Vite 构建的 Chrome 插件，支持侧边栏面板功能。

image.png

🚀 功能特性

  • ✅ 现代化的 React 18 + TypeScript 开发环境
  • ✅ Vite 构建工具，快速热重载
  • ✅ Chrome Manifest V3 支持
  • ✅ Side Panel API 集成
  • ✅ 标签页管理功能
  • ✅ 响应式 UI 设计
  • ✅ 完整的开发工具链

📁 项目结构

chorm-tool/
├── public/
│   ├── manifest.json          # Chrome 插件配置文件
│   └── icons/                 # 插件图标目录
├── src/
│   ├── sidepanel.html         # 侧边栏 HTML 入口
│   ├── sidepanel.tsx          # 侧边栏 React 入口
│   ├── App.tsx                # 主应用组件
│   ├── App.css                # 样式文件
│   ├── background.ts          # 后台脚本
│   └── content.ts             # 内容脚本
├── scripts/
│   ├── build.sh               # 构建脚本
│   └── dev.sh                 # 开发脚本
├── package.json               # 项目配置
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
└── README.md                  # 项目说明

📋 功能说明

侧边栏功能

  • 显示当前活动标签页信息
  • 记录当前页面API请求记录
  • 请求后端API日志信息
  • 模糊搜索匹配API及日志信息
  • 通过types和levels去筛选日志及API记录信息
  • 设置及重置page domain和API domain

权限说明

  • sidePanel: 启用侧边栏功能
  • activeTab: 访问当前活动标签页
  • storage: 本地存储数据（主要缓存记录配置的domain）
  • webRequest:请求API
  • webNavigation:导航记录

🎨 自定义开发

添加新功能

  1. 在 src/App.tsx 中添加新的 UI 组件
  2. 在 src/background.ts 中添加后台逻辑
  3. 在 src/content.ts 中添加页面交互功能

修改样式

编辑 src/App.css 文件来自定义界面样式。

添加新权限

在 public/manifest.json 中的 permissions 数组添加新权限。

🔍 调试

开发工具

  • 侧边栏：右键点击插件图标 → 检查弹出内容
  • 后台脚本：chrome://extensions/ → 插件详情 → 检查视图：Service Worker
  • 内容脚本：在任意网页按 F12 → Console

常见问题

  1. 插件无法加载：检查 manifest.json 语法是否正确
  2. 权限被拒绝：确认 manifest.json 中已添加所需权限
  3. 样式不生效：检查 CSS 文件是否正确引入

📦 构建输出

构建完成后，dist 目录包含：

  • sidepanel.html - 侧边栏页面
  • sidepanel.js - 侧边栏脚本
  • background.js - 后台脚本
  • content.js - 内容脚本
  • manifest.json - 插件配置
  • icons/ - 图标文件

Service Worker 问题描述

Chrome扩展的Service Worker不支持ES6模块语法（import/export），导致以下错误：

Service worker registration failed. Status code: 15
Uncaught SyntaxError: Unexpected token 'export'

解决方案

1. 使用 IIFE 格式打包

修改了构建配置，将 src/background/index.ts 文件打包为 IIFE（立即执行函数表达式）格式：

  • ✅ 使用 Vite 的 lib 模式单独构建 background 脚本
  • ✅ 输出格式设置为 iife，避免顶层模块语法
  • ✅ 所有 import/export 都被打包成自执行脚本
  • ✅ 兼容Chrome Service Worker环境

2. 创建专门的构建配置

创建了 vite.background.config.ts 配置文件：

export default defineConfig({
  build: {
    lib: {
      entry: 'src/background/index.ts',
      name: 'BackgroundBundle',
      fileName: 'background',
      formats: ['iife'] // 输出为 IIFE 格式
    },
    rollupOptions: {
      output: {
        inlineDynamicImports: true // 内联所有依赖
      }
    }
  }
})

3. 更新构建脚本

修改了 scripts/build-sw.sh 脚本来：

  • 分别构建 sidepanel/content 和 background
  • 使用专门的配置构建 background 脚本
  • 自动重命名输出文件
  • 验证 Service Worker 格式

4. 更新package.json

添加了新的构建命令：

{
  "scripts": {
    "build:background": "vite build --config vite.background.config.ts",
    "build:extension": "npm run build && npm run build:background && npm run copy:manifest",
    "build:sw": "./scripts/build-sw.sh"
  }
}

使用方法

构建扩展

# 使用新的Service Worker构建脚本
npm run build:sw

# 或者分步构建
npm run build:extension

验证构建结果

构建完成后，检查 dist/background.js 文件：

# 检查是否包含ES6模块语法
grep -n "import\|export" dist/background.js

# 如果没有输出，说明构建成功

技术细节

Service Worker限制

Chrome扩展的Service Worker有以下限制：

  1. 不支持ES6模块: 不能使用 import/export
  2. 不支持某些Web API: 如 window 对象
  3. 生命周期限制: 会被浏览器自动终止和重启
  4. 存储限制: 需要使用Chrome Storage API或IndexedDB

解决方案特点

  1. 保持功能完整: 所有原有功能都保持不变
  2. 使用IndexedDB: 继续使用IndexedDB存储数据
  3. 兼容性好: 支持所有Chrome版本
  4. 构建简单: 一键构建，自动验证

如果仍然出现ES6模块错误

  1. 检查 dist/background.js 是否包含 import/export
  2. 确认使用了 npm run build:sw 而不是 npm run build
  3. 清理构建目录后重新构建
avatar
文章
阅读
粉丝