用途
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。