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）

可用模块

构建命令

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 构建时，以下清单转换会自动应用：

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

环境变量

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

License

MIT