2025-01-11

chrome 插件基础模板

一直以来，都觉得 chrome 插件挺方便的，可以做出灵活又好用的工具。工作中也接触过一些插件的开发，但是都没有系统的了解下。这次花点时间记录下。

因为刚好发现这个工具《What is CRXJS》，用 vite 做开发工具，支持前端框架有 react、vue、solid 等。这样一来就省了很多事了，chrome 插件也可以使用漂漂亮亮的组件库了。

具体有《官方文档》，这里记录一下快速使用的点。

注意：
1. 最新 chrome 浏览器版本已经禁止的 manifest_version 2 版本的使用了，现在开始都是 3 了。
2. 这个 @crxjs/vite-plugin 工具要使用 beta 版本，latest 在 manifest_version 3 会因为资源安全问题加载报错。

介绍

以 manifest 的字段为介绍：

{
  "manifest_version": 3,
  "name": "Chrome Extension",
  "version": "1.0.0",
  "description": "Chrome Extension React Vite Example",
  "permissions": ["tabs", "notifications"],
  "action": {
    "default_popup": "src/popup/index.html",
    "default_icon": "src/assets/images/icon.png"
  },
  "icons": {
    "16": "src/assets/images/icon-16.png",
    "32": "src/assets/images/icon-32.png",
    "48": "src/assets/images/icon-48.png",
    "128": "src/assets/images/icon-128.png"
  },
  "background": {
    "service_worker": "src/background/index.ts",
    "type": "module"
  },
  "content_scripts": [
    {
      "js": ["src/scripts/content.ts"],
      "matches": ["<all_urls>"]
    }
  ]
}

permissions：声明要开通的模块，不然调用 api 会失败。
action：就是右上角插件面板里，那个按钮点击后弹出框的入口文件和显示图标。
background：后台运行的代码，这里可以调用的 api 更全一点。可以指定以 es module 模式加载。
content_scripts：会嵌入到当前访问网站里，可以读取当前网站的 dom，storage 等，实际就是当前网站的一部分了。matches 可以指定哪些网站可以嵌入。具体可以看《匹配模式》。

示例工程，用了多页面，但是这个 @crxjs/vite-plugin 只默认加载了 action 做入口文件。所以要自己配一下其它入口页面。

import { resolve } from 'node:path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { crx, type ManifestV3Export } from '@crxjs/vite-plugin';
import manifest from './manifest.json';

export default defineConfig({
  plugins: [react(), crx({ manifest: manifest as ManifestV3Export })],
  build: {
    rollupOptions: {
      input: {
        main: resolve(__dirname, 'src/main/index.html'),
      },
    },
  },
});

开发

像往常一样启动 vite 工程就行，只不过配置了开发时也把文件存在硬盘，因为要丢到插件库里去运行。执行 pnpm dev 后就会产出 dist 文件夹，浏览器打开 chrome://extensions/，然后把整个 dist 文件夹往浏览器界面拖就行。当然右上角的开发者模式要打开。
chrome://extensions 页面 “所有扩展程序” 下，有自己的开发程序那就是成功了。大部分代码更新都是可以马上生效不需要刷新加载的。改了配置之类的就得刷新加载，此时点击该插件面板右下角的刷新按钮就行了。