chrome-plugin-creator

Chrome 插件开发脚手架，支持 Popup、SidePanel、Background、Content Script 全形态，内置丰富工具库，开箱即用。

特性

• 全形态支持：Popup 弹窗、SidePanel 侧边栏、Background Service Worker、Content Script 一应俱全
• 现代技术栈：TypeScript + React 18 + Ant Design 5 + Tailwind CSS + Webpack 5
• 内置工具库：消息通信、Storage 封装、登录认证、DOM 操作、控制台捕获、页面截图等
• Manifest V3：采用最新 MV3 规范，符合 Chrome 安全要求
• 高性能构建：esbuild-loader 极速构建，filesystem cache 二次构建提速

安装

npm install -g chrome-plugin-creator
# 或
npx chrome-plugin-creator my-plugin

使用

# 创建新项目
chrome-plugin-creator my-chrome-plugin

# 简写
cpc my-chrome-plugin

# 带选项
cpc my-plugin --description "我的插件描述" --skip-install

生成的项目结构

my-chrome-plugin/
├── public/
│   ├── manifest.json          # 插件清单（MV3）
│   ├── popup.html             # Popup 页面模板
│   ├── sidepanel.html         # SidePanel 页面模板
│   ├── console-interceptor.js # 控制台拦截脚本（主世界执行）
│   └── icons/                 # 插件图标
├── src/
│   ├── background.ts          # Service Worker
│   ├── content.tsx            # Content Script 入口
│   ├── sidepanelEntry.tsx     # SidePanel 入口
│   ├── popup/
│   │   ├── popup.tsx          # Popup 入口
│   │   ├── index.tsx          # Popup 主组件
│   │   └── popup.scss
│   ├── sidepanel/
│   │   ├── index.tsx          # SidePanel 主组件
│   │   └── sidepanel.scss
│   ├── content/
│   │   └── index.tsx          # Content 浮层组件
│   ├── utils/
│   │   ├── messaging.ts       # 消息通信工具
│   │   ├── storage.ts         # Chrome Storage 封装
│   │   ├── auth.ts            # 登录认证工具
│   │   ├── dom.ts             # DOM 操作工具
│   │   ├── consoleCapture.ts  # 控制台捕获工具
│   │   ├── pageCapture.ts     # 页面截图工具
│   │   ├── browserListeners.ts # 浏览器事件监听
│   │   ├── request.ts         # 网络请求工具
│   │   └── index.ts           # 统一导出
│   ├── styles/
│   │   └── tailwind.css
│   └── types/
│       └── global.d.ts
├── webpack.config.js
├── tsconfig.json
├── tailwind.config.js
├── postcss.config.js
└── package.json

开发命令

cd my-chrome-plugin
npm install

# 开发模式（监听文件变更）
npm run start

# 生产构建
npm run build

加载插件到 Chrome

1. 打开 Chrome，访问 chrome://extensions
2. 开启右上角「开发者模式」
3. 点击「加载已解压的扩展程序」
4. 选择项目的 dist/ 目录

内置工具库文档

消息通信（messaging.ts）

Chrome 插件各组件间的通信：

import { sendToBackground, sendToActiveTab, onMessage, connectToBackground } from './utils/messaging';

// 向 background 发送消息（popup/sidepanel/content → background）
const result = await sendToBackground({ action: 'openSidePanel', tabId: 123 });

// 向当前活动 tab 的 content script 发送消息
await sendToActiveTab({ action: 'showFloating', message: 'Hello!' });

// 监听消息
const cleanup = onMessage((request, sender, sendResponse) => {
  if (request.action === 'ping') {
    sendResponse({ pong: true });
    return true; // 异步响应时必须返回 true
  }
});

// 建立长连接（sidepanel 用于感知关闭事件）
const port = connectToBackground('sidepanel');
port.onDisconnect.addListener(() => console.log('连接断开'));

Storage 封装（storage.ts）

import { getStorage, setStorage, setCache, getCache } from './utils/storage';

// 读写 local storage
await setStorage({ userInfo: { name: 'Alice' } });
const { userInfo } = await getStorage(['userInfo']);

// 带 TTL 的缓存（1小时过期）
await setCache('apiData', responseData, 3600_000);
const cached = await getCache('apiData'); // null 表示已过期

登录认证（auth.ts）

import { saveCredentials, tryAutoLogin, loginWithJSON } from './utils/auth';

// 保存凭证
await saveCredentials('username', 'password');

// 自动登录
const result = await tryAutoLogin('https://api.example.com/login');

// 通过 background 代理发送登录请求（携带 Cookie）
const result = await loginWithJSON('https://api.example.com/login', {
  username: 'user',
  password: btoa('pass'),
});

DOM 操作（dom.ts）

import { waitForElement, fillInput, findElementByText, highlightElement } from './utils/dom';

// 等待元素出现
const input = await waitForElement<HTMLInputElement>('input[placeholder*="手机号"]');

// 填充表单（兼容 React 受控组件）
fillInput(input, '13800138000');

// 查找含文本的元素
const btn = findElementByText('button', '获取验证码');

// 高亮元素
const removeHighlight = highlightElement(btn);
setTimeout(removeHighlight, 2000);

控制台捕获（consoleCapture.ts）

import { injectConsoleCapture, enableConsoleCapture, listenToConsoleLogs } from './utils/consoleCapture';

// 在 content script 入口注入（越早越好）
injectConsoleCapture();

// 开启捕获
enableConsoleCapture();

// 监听日志
const cleanup = listenToConsoleLogs((log) => {
  console.log(`[${log.type}]`, log.args, log.url);
});

页面截图（pageCapture.ts）

import { captureFullPage, captureViewport } from './utils/pageCapture';

// 截取完整页面
const base64 = await captureFullPage({ maxWidth: 1280, quality: 0.8 });

// 截取可视区域
const viewportBase64 = await captureViewport();

浏览器事件监听（browserListeners.ts）

import { onTabActivated, onActiveTabUrlChange, onStorageKeyChange } from './utils/browserListeners';

// 监听 tab 切换
const cleanup = onTabActivated(({ tabId }) => {
  console.log('切换到 tab:', tabId);
});

// 监听当前活动 tab 的 URL 变化
const cleanup2 = onActiveTabUrlChange((url, tabId) => {
  console.log('URL 变化:', url);
});

// 清理监听
cleanup();
cleanup2();

网络请求（request.ts）

import { request, get, post, postForm } from './utils/request';

// 通用请求（通过 background 代理，携带 Cookie）
const result = await request<User>('https://api.example.com/user');

// GET 快捷
const data = await get<UserList>('https://api.example.com/users');

// POST JSON
const res = await post('https://api.example.com/create', { name: 'Alice' });

// POST 表单
const loginRes = await postForm('https://api.example.com/login', { username: 'u', password: 'p' });

发布到 npm

# 登录 npm
npm login

# 发布
npm publish

License

MIT