CRXJS Vite插件教程：手把手教你搭建支持热更新的浏览器扩展开发环境
一、为什么需要专门的浏览器扩展脚手架
传统开发的痛点
很多开发者都有过开发浏览器插件的经历，传统的开发方式通常比较原始。你需要手动创建manifest.json文件，编写各种脚本，然后通过浏览器的扩展管理页面手动加载未打包的扩展。每次修改代码后，你还得回到扩展管理页面点击刷新按钮，有时候甚至需要重启浏览器才能看到效果。这种反复的手动操作非常浪费时间，尤其是在调试样式或者调整交互逻辑的时候，频繁的刷新会让开发体验变得很差。
另外，传统的插件开发缺乏现代化的工具支持。你没有热更新、没有模块热替换、没有TypeScript类型检查，甚至连ES Module的支持都很有限。这意味着你需要自己处理很多底层的事情，比如资源的打包、代码的压缩等等。这些问题叠加在一起，使得浏览器扩展的开发效率远低于常规的前端项目。
CRXJS Vite插件带来的改变
CRXJS Vite插件就是为了解决上述问题而诞生的。它基于Vite这个现代化的构建工具，把Vite优秀的开发体验带到了浏览器扩展开发中。最吸引人的特性就是热更新功能，当你修改代码后，浏览器扩展会自动更新，不需要你手动去刷新。这就好比你在开发普通网页时修改CSS，浏览器立即就能呈现新效果一样，非常流畅。
除了热更新，CRXJS还提供了对浏览器扩展API的类型支持。这意味着你在编写background script、content script或者popup页面时，编辑器能给你提供准确的代码提示和类型检查。比如你调用chrome.tabs.query方法时，IDE会自动告诉你这个方法需要什么参数，返回什么数据，大大减少了查阅文档的时间。
二、准备工作与环境搭建
系统要求
在使用CRXJS Vite插件之前，你需要确保电脑上已经安装了Node.js环境。建议使用Node.js的长期支持版本，比如16.x或者18.x，这些版本稳定且兼容性好。另外，你需要一个现代的浏览器，Chrome或者Edge都可以，因为这两个浏览器都支持Chromium内核的扩展标准。
初始化项目
开始搭建项目的第一步是创建一个新的目录作为你的扩展项目文件夹。你可以手动创建，也可以使用命令行来创建。假设我们把这个项目叫做my-chrome-extension，那么在命令行中输入以下命令：
mkdir my-chrome-extension
cd my-chrome-extension进入项目目录后，我们需要初始化一个npm项目。运行npm init命令，然后按照提示填写项目名称、版本号等信息。当然你也可以直接使用npm init -y来快速生成默认的package.json文件，后续再根据需要修改。
安装核心依赖
接下来需要安装三个核心的依赖包。第一个是Vite本身，它是整个构建系统的基础。第二个是CRXJS Vite插件，它是实现热更新和类型支持的灵魂组件。第三个是你想要使用的前端框架，比如React或者Vue。这里我们以React为例进行说明。
在命令行中执行以下安装命令：
npm install vite @crxjs/vite-plugin react react-dom如果你使用的是pnpm或者yarn，也可以用对应的包管理器命令。安装完成后，你会看到package.json文件中多了这几个依赖项。
三、配置文件详解
Vite配置文件
在项目根目录下创建一个vite.config.js文件，这是Vite的核心配置文件。我们需要在这个文件中引入CRXJS插件并进行配置。基本的配置代码如下：
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 }),
],
})这段代码做了几件事情。首先引入了React插件，这样我们就可以在扩展中使用JSX语法和React的特性。然后引入了CRXJS插件，并把manifest.json文件的路径传给它。CRXJS会根据manifest.json的内容自动处理扩展的各种入口文件和资源。
Manifest文件
Manifest.json是浏览器扩展的灵魂文件，它定义了扩展的基本信息、权限、入口脚本等内容。CRXJS对manifest.json有一些特殊的要求，主要是入口文件的写法需要遵循特定的格式。下面是一个简单的示例：
{
"manifest_version": 3,
"name": "我的第一个扩展",
"version": "1.0.0",
"description": "这是一个使用CRXJS开发的Chrome扩展",
"permissions": ["storage", "activeTab"],
"action": {
"default_popup": "src/popup/index.html"
},
"background": {
"service_worker": "src/background/index.ts",
"type": "module"
},
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["src/content/index.ts"]
}
]
}注意这里的入口文件路径指向的是源代码目录下的文件，而不是打包后的产物。CRXJS会自动处理这些文件，在开发模式下提供热更新，在生产构建时进行打包和优化。
四、编写扩展代码
Popup页面的开发
Popup页面是用户点击浏览器工具栏上的扩展图标时弹出的窗口。我们可以像开发普通React应用一样来编写这个页面。在src/popup目录下创建index.html和main.tsx文件。
Index.html是一个标准的HTML文件，但需要注意它不包含常规的script标签，因为CRXJS会自动注入必要的脚本。Main.tsx则是React应用的入口点：
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
const root = document.createElement('div')
document.body.appendChild(root)
ReactDOM.createRoot(root).render(
<React.StrictMode>
<App />
</React.StrictMode>
)在App组件中，你可以编写任何React代码。比如一个简单的计数器，或者显示当前页面信息的组件。最重要的是，当你修改这些代码时，浏览器中的popup窗口会自动更新，不需要你关闭重新打开。
Background脚本的编写
Background脚本是扩展的后台逻辑部分，它在浏览器后台持续运行。CRXJS支持使用TypeScript编写background脚本，并且提供了完整的类型支持。在src/background/index.ts中，你可以这样写：
chrome.runtime.onInstalled.addListener(() => {
console.log('扩展已安装')
})
chrome.action.onClicked.addListener((tab) => {
chrome.tabs.sendMessage(tab.id!, { type: 'TOGGLE' })
})这段代码实现了两个基本功能：监听扩展安装事件，以及监听用户点击扩展图标的事件。当用户点击图标时，向当前标签页发送一条消息。由于CRXJS提供了类型支持，你在编写这些代码时会有完善的代码提示。
Content Script的编写
Content script是注入到网页中运行的脚本，它可以读取和修改网页的内容。在src/content/index.ts中，我们可以编写与页面交互的逻辑：
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === 'TOGGLE') {
const overlay = document.createElement('div')
overlay.textContent = 'Hello from extension'
document.body.appendChild(overlay)
}
})这段代码监听从background发送过来的消息，然后在当前页面上创建一个浮层元素。同样地，当你修改content script的代码时，已经打开的网页中的脚本也会自动更新，这在调试时非常方便。
五、启动开发模式
运行开发服务器
一切准备就绪后，就可以启动开发模式了。在package.json中添加一个dev脚本：
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}然后在命令行中运行npm run dev。Vite会启动一个开发服务器，并在控制台输出一些信息，包括扩展的ID和加载方式。通常情况下，CRXJS会自动打开浏览器并加载你的扩展。如果没有自动打开，你可以根据控制台的提示手动操作。
在浏览器中加载扩展
当开发服务器运行后，打开Chrome浏览器，进入扩展管理页面。开启右上角的"开发者模式"，然后点击"加载已解压的扩展程序"。在弹出的文件选择器中，找到你的项目目录下的dist文件夹（CRXJS会在开发模式下自动生成这个文件夹），选中并确认加载。
加载成功后，你会看到你的扩展出现在列表中。现在，当你修改任何源代码文件时，扩展都会自动更新。比如你修改了popup页面的样式，只需要保存文件，再点击扩展图标，就能看到最新的效果。
六、生产构建与发布
构建生产版本
当你完成开发并测试无误后，就可以构建生产版本了。运行npm run build命令，Vite会对所有代码进行打包、压缩和优化。构建完成后，dist目录中会生成最终的文件，包括优化后的manifest.json、压缩后的JavaScript和CSS文件。
打包成CRX文件
如果需要发布到Chrome Web Store，你需要将扩展打包成.crx文件。在Chrome的扩展管理页面，找到你的扩展，点击"打包扩展程序"按钮，选择dist目录作为扩展的根目录，然后点击"打包扩展程序"。Chrome会生成一个.crx文件和一个.pem私钥文件。请妥善保管私钥文件，因为后续更新扩展时需要用到同一个私钥。
七、常见问题与解决方案
热更新不生效
如果你发现修改代码后扩展没有自动更新，可以检查以下几点。首先确认开发服务器是否正常运行，查看控制台有没有报错信息。其次检查manifest.json中的入口文件路径是否正确，CRXJS依赖于这些路径来监控文件变化。最后尝试重新加载扩展，有时候浏览器缓存会导致更新延迟。
TypeScript类型错误
如果在编写代码时遇到类型错误，可能是缺少相关的类型声明文件。浏览器扩展的API类型通常包含在@types/chrome包中，你可以通过npm install @types/chrome --save-dev来安装。安装后，TypeScript就能正确识别chrome.*命名空间下的所有方法和属性。
跨域请求问题
浏览器扩展在发起网络请求时有特殊的权限要求。如果你需要在扩展中访问外部API，记得在manifest.json的permissions字段中添加对应的域名，或者使用host_permissions字段来指定允许访问的网址范围。
八、总结
CRXJS Vite插件为浏览器扩展开发带来了现代化的开发体验。通过热更新功能，开发者可以实时看到代码变更的效果，大大缩短了开发周期。配合Vite的高速构建能力和TypeScript的类型支持，整个开发过程变得更加顺畅和高效。
如果你是第一次接触浏览器扩展开发，不妨从本文的示例开始，逐步尝试更多高级功能。随着你对CRXJS的熟悉，你会发现开发浏览器扩展不再是件麻烦事，反而成为一种享受。
CRXJSVite插件浏览器扩展热更新TypeScript修改时间：2026-08-01 04:04:47