webexter

基于 Vite 8 + Manifest V3 的跨平台浏览器扩展脚手架工具。

功能特性

• 框架支持 — React 19 或 Vue 3，提供 TypeScript 和 JavaScript 两种语言选项
• 模块化脚手架 — 按需选择页面：background、content script、popup、options、side panel、new tab page、devtools
• 跨平台构建 — 通过 --mode 标志即可构建 Chrome、Firefox 或任意 Chromium 内核浏览器版本
• Firefox 兼容 — 自动处理清单文件差异（browser_specific_settings、sidebar_action、options_ui）
• 热更新支持 — 扩展页面开箱即用的热模块替换
• WebSocket CSP — 内容安全策略已预配置，支持扩展 HMR 连接
• webextension-polyfill — 预装跨浏览器 API 兼容层

快速开始

npx webexter create my-extension
cd my-extension
pnpm install
pnpm dev       # 开发模式 (Chrome)

然后在浏览器中加载 dist 文件夹作为未打包扩展程序。

使用方法

webexter create <项目名称>

按提示操作：

1. 框架 — React / Vue
2. 语言 — TypeScript / JavaScript
3. 模块 — 多选所需页面（默认：popup + background）

可用模块

模块	描述	Manifest Key
Background (Service Worker)	扩展后台服务 worker	background.service_worker
Content Script	注入到网页的脚本	content_scripts
Popup	浏览器工具栏弹出窗口	action.default_popup
Options Page	扩展设置页面	options_page
Side Panel	浏览器侧边栏面板	side_panel
New Tab Page	新标签页	chrome_url_overrides.newtab
DevTools Page	DevTools 扩展面板	devtools_page

构建命令

命令	模式	输出
pnpm dev	default	开发模式 (Chrome)
pnpm dev:chrome	chrome	开发模式 (Chrome)
pnpm dev:firefox	firefox	开发模式 (Firefox)
pnpm build	production	生产构建
pnpm build:chrome	chrome	生产构建 (Chrome)
pnpm build:firefox	firefox	生产构建 (Firefox)

pnpm dev 启动带 HMR 的 Vite 开发服务器。在浏览器中加载 dist/ 作为未打包扩展程序。

pnpm build 在 dist/ 中生成生产构建产物。

使用 --mode <name> 可针对任意 Chromium 内核浏览器（如 --mode qq、--mode edge）。只有 firefox 模式会触发 Firefox 特定的清单转换，其他模式均使用标准 Chrome 清单格式。

生成的项目结构

my-extension/
├── package.json
├── vite.config.ts
├── manifest.json
├── tsconfig.json / jsconfig.json
├── .env
├── .env.firefox
└── src/
    ├── env.d.ts              # (仅 TypeScript)
    ├── background/
    │   └── index.ts
    ├── content/
    │   └── index.ts
    ├── popup/
    │   ├── index.html
    │   ├── main.tsx
    │   └── App.tsx
    ├── options/
    │   ├── index.html
    │   ├── main.tsx
    │   └── App.tsx
    ├── sidepanel/
    │   ├── index.html
    │   ├── main.tsx
    │   └── App.tsx
    ├── newtab/
    │   ├── index.html
    │   ├── main.tsx
    │   └── App.tsx
    ├── devtools/
    │   ├── index.html
    │   ├── devtools.ts
    │   └── devtools.js
    ├── public/
    └── ...

仅生成所选的模块。

Firefox 兼容性

使用 --mode firefox 构建时，以下清单转换会自动应用：

功能	Chrome	Firefox
插件 ID	不需要	browser_specific_settings.gecko.id
侧边栏面板	side_panel	sidebar_action
选项页面	options_page	options_ui（带 open_in_tab）

webextension-polyfill 包提供跨浏览器 API 兼容性（在所有浏览器中使用 browser.* API）。

环境变量

变量	用途
VITE_FIREFOX_ID	Firefox 插件 ID（默认：<project>@example.com）

在 .env（通用）或 .env.firefox（仅 Firefox）中定义自定义变量。

License

MIT