SuperAPI AI 工具集

crxjs

编程与开发

查看项目

更新于 10-16 12:15

技能介绍

用途

CRXJS 是一个 Chrome 扩展(浏览器插件)开发工具,以 Vite 插件 @crxjs/vite-plugin 的形式工作。它的核心价值是为扩展的各个上下文提供真正的 HMR:popup、options 页面、content scripts 和 side panel。它会读取你的 manifest 自动生成扩展输出,处理 content script 注入,并管理 service worker 的构建。

项目状态

  • 包名:@crxjs/vite-plugin(v2.x 稳定版,截至 2026 年 3 月最新为 v2.4.0)
  • 脚手架:npm create crxjs@latest(建议始终使用 @latest)
  • 维护者:@Toumash 和 @FliPPeDround(自 2025 年中期起)
  • GitHub:github.com/crxjs/chrome-extension-tools(约 4k stars)
  • Vite 兼容性:v3 至 v8-beta

主要能力

真 HMR

按上下文区分:popup、options、side panel 均为完整 HMR,基于 WebSocket,保留状态;manifest 中声明的 content script 为真 HMR,CRXJS 会注入 loader 与 HMR 客户端;动态 content script 通过 ?script 导入同样获得真 HMR;service worker 为自动重载(改动触发整个扩展重新加载);main world 脚本不支持 HMR,会被 CRXJS loader 跳过。

content script 的 HMR 之所以可行,是因为 CRXJS 生成了一个 loader 脚本,它导入 HMR preamble、HMR 客户端以及你的实际脚本,从而在不整页刷新的情况下实现真正的模块级 HMR。这是 CRXJS 的主要差异化点。

defineManifest

除了静态 JSON,还可使用 CRXJS 的 defineManifest 获得动态值与完整的 TypeScript 自动补全,例如根据 config.command 区分开发/生产环境的扩展名称。

在 src/vite-env.d.ts 或 src/crxjs.d.ts 中添加 /// <reference types="@crxjs/vite-plugin/client" /> 可为 ?script 与 ?script&module 导入启用类型。

动态 content script 导入

对于以编程方式注入(而非写在 manifest 中)的 content script,CRXJS 提供特殊导入后缀。?script 返回可用于 chrome.scripting.executeScript 的解析后路径;?script&module 用于 main world 注入(无 HMR)。

插件选项

crx() 可接受 manifest、browser('chrome' | 'firefox')、contentScripts.injectCss(是否自动为 content script 注入 CSS)、contentScripts.hmrTimeout(HMR 连接超时毫秒数)等选项。

使用方式

脚手架创建新项目(交互式选择框架):

npm create crxjs@latest

在既有 Vite 项目中安装:

npm install @crxjs/vite-plugin -D

以 React 为例的 Vite 配置:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./manifest.json";

export default defineConfig({
  plugins: [react(), crx({ manifest })],
});

建议搭配 @vitejs/plugin-react(而非 plugin-react-swc)以获得最佳 HMR 兼容性。若必须使用 SWC,可按资料中的方式对 manifest 做类型转换。Vue、Svelte 与原生 TypeScript 的配置方式与此类似,仅框架插件不同。

开发流程:运行 npm run dev(输出到 dist/ 并带 HMR),打开 chrome://extensions,启用开发者模式,点击“加载已解压的扩展程序”,选择 dist/ 目录;随后编辑代码,popup/content script 会即时更新;service worker 改动会触发扩展自动重新加载。首次加载后,后续 npm run dev 会话会自动重连,除非 manifest.json 变化,否则无需重新加载扩展。

生产构建:npm run build 输出到 dist/,可打包为 zip 上传至 Chrome Web Store(cd dist && zip -r ../extension.zip .)。建议设置 build: { modulePreload: false } 以避免内联脚本被 CWS 拒绝。

适用场景与选型建议

适合希望以最小抽象直接使用原生 Chrome API、并且最看重 content script HMR 的开发者。CRXJS 保持“不挡路”:没有魔法路由,没有封装 API,只有你的代码加 HMR。

与其他方案的对比(按资料):

  • CRXJS:content script 为真 HMR;支持任意 Vite 框架;抽象层薄(Vite 插件);无消息辅助、无存储封装;跨浏览器支持 Chrome + Firefox;无基于文件的路由;学习曲线低。
  • WXT:content script 为基于文件的重载;支持任意框架;完整框架;内置消息与存储辅助;支持 Chrome + Firefox + Safari;有基于文件的路由;学习曲线中等。
  • Plasmo:content script 为部分 HMR;偏 React;完整框架;内置消息与存储辅助;支持 Chrome + Firefox;有基于文件的路由;学习曲线中等。

选择建议:想要对原生 Chrome API 的最小抽象并优先 content script HMR 时选 CRXJS;想要约定、内置工具与跨浏览器支持时选 WXT;偏 React 且想要最高层抽象时选 Plasmo。

已知问题与变通

  • Tailwind CSS 在 content script 中的 HMR:新增的 Tailwind 类可能不会触发 content script 的 CSS 更新,变通方法是添加新工具类后重启 dev server(v2.4.0 有改进但未完全解决),并确保配置中 injectCss: true。
  • WebSocket 连接错误(ws://localhost:undefined/):原因是 dev server 与 HMR 配置端口不一致,可将两者显式设为同一值(如 port: 5173, strictPort: true, hmr: { port: 5173 })。
  • “Manifest version 2 is deprecated” 警告:说明 manifest 被当作 MV2 解析,需确保 "manifest_version": 3。
  • content script 在 file:// URL 上不注入:Chrome 要求用户在 chrome://extensions 的扩展设置中启用“允许访问文件网址”,CRXJS 无法改变这一点。
  • Chrome 更新后 HMR 失效:CRXJS 的 HMR 依赖注入连接到 dev server WebSocket 的 content script,Chrome 安全更新偶尔会破坏此机制,变通方法是升级到最新的 CRXJS 版本。

限制

资料未提供除上述之外的能力、收费或价格信息;CRXJS 不提供消息辅助与存储封装,需直接使用 chrome.*;不支持基于文件的路由。如遇 bug 或异常行为,可在 github.com/crxjs/chrome-extension-tools/issues 提交 issue。