Quasar BEX 后台脚本(Background Script)实战指南:从 Manifest 注册到事件通信

发布时间:2026/11/19 2:32:21

Quasar BEX 后台脚本(Background Script)实战指南:从 Manifest 注册到事件通信 Quasar BEX 后台脚本Background Script实战指南从 Manifest 注册到事件通信【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar本文是 Quasar Framework 的 BEXBrowser Extension浏览器扩展开发系列指南之一聚焦于quasar/app-vite模式下后台脚本Background Script的完整开发流程如何在/src-bex/manifest.json中注册后台脚本、如何用 BEX Bridge 将浏览器事件如新标签页打开推送到 Quasar App 内部以及 Manifest v3 下 Service Worker 生命周期带来的连接管理问题。读完本文你将能够独立编写一个可监听浏览器扩展事件并与 Quasar 应用双向通信的后台脚本。后台脚本的定位BEX 的事件中枢后台脚本运行在 BEX 自身的上下文context中是唯一可以监听所有浏览器扩展事件的地方——包括chrome.tabs、chrome.runtime、chrome.webNavigation、chrome.storage等扩展 API 提供的事件。与注入到网页中的内容脚本Content Script不同后台脚本不受目标页面 DOM 与 CSP 的限制因此适合承担全局状态维护、跨标签页协调、调用高权限 API 等职责。在 Quasar 的 BEX 架构中后台脚本还有一个特殊身份它是 BEX Bridge 通信的中心节点。所有消息都经由后台脚本中的 bridge 转发到正确的接收方详见 BEX Bridge 通信文档。[!WARNING] 在 Chrome 的 Manifest v3 中后台脚本实际上是一个Service Worker这一情况目前撰写本文档时尚不适用于 Firefox 的 Manifest v3。这直接影响后台脚本的生命周期与内存状态后文生命周期一节会专门展开。注册后台脚本以/src-bex/manifest.json为准/src-bex/manifest.json是定义整个 BEX 的中央配置后台脚本也在这里声明。由于 Chrome 与 Firefox 对后台脚本的声明方式不同Quasar 的 BEX manifest 支持按目标浏览器拆分配置chrome: { background: { service_worker: background.js } }, firefox: { background: { scripts: [ background.js ] } }两个关键点需要留意ChromeMV3使用service_worker字段只允许声明一个后台 Service WorkerFirefoxMV2/MV3使用scripts数组允许声明多个后台脚本。TS 开发者请注意你的后台脚本与内容脚本文件扩展名是.ts那么在 manifest.json 中也请写.ts——例如background.ts、my-content-script.ts。虽然浏览器厂商只认.js扩展名但 Quasar CLI 会在构建阶段自动把扩展名转换为.js。源码印证扩展名如何被自动转换manifest.json中声明的脚本并非原样打包。在 bex-utils.js 中createManifest()会解析 manifest 并调用extractBexScripts()提取所有脚本入口对background.service_worker与background.scripts中的每一项先通过正则/\.[jt]sx?$/i去掉.ts/.js/.tsx/.jsx扩展名再统一改写为.js写入最终生成的 manifest对应代码见 bex-utils.js同时按name - distDir/脚本名.js的映射生成编译入口让 Vite 把源文件含 TS真正编译成浏览器可执行的 JS若声明的文件不存在构建时会输出警告并跳过该入口。也就是说你在/src-bex/下书写background.ts最终产物中的manifest.json会自动指向编译后的background.js无需手动维护两份清单。extendBexManifestJson配置钩子见 bex-utils.js还允许你在quasar.config.js或应用扩展中进一步改写 manifest。后台脚本的入口与桥初始化项目模板会在创建 BEX 时生成后台脚本骨架JS 模板 与 TS 模板 内容基本一致。脚本开头的导入是强制要求/** * Importing the file below initializes the extension background. * * Warnings: * 1. Do NOT remove the import statement below. It is required for the extension to work. * If you dont need createBridge(), leave it as import #q-app/bex/background. * 2. Do NOT import this file in multiple background scripts. Only in one! * 3. Import it in your background service worker (if available for your target browser). */ import { createBridge } from #q-app/bex/background const bridge createBridge({ debug: false })#q-app/bex/background是 Quasar CLI 为 BEX 后台脚本注入的虚拟模块其实现在 app-vite/exports/bex/background.js。源码层面的三个实现细节值得了解单例保护模块内部通过scriptHasBridge标志位确保createBridge()在同一个后台脚本中只能调用一次重复调用会输出Background Quasar Bridge has already been created.并直接返回见 background.js。BEX Bridge 文档也明确警告即便 manifest 中声明了多个后台脚本也只能在其中某一个脚本里创建 bridge。开发模式 HMR当QUASAR_DEV且目标为 Chrome 时该模块会自动拦截扩展页面发往 Vite dev server 的 fetch 请求interceptRequests并通过 WebSocket 建立 HMR 通道收到qbex:hmr:reload事件后通知所有内容脚本并调用chrome.runtime.reload()热重载整个扩展见 background.js。这解释了为何后台脚本模板不允许被删除——它同时承担了构建期的桥初始化与开发期的 HMR 基建。双浏览器兼容BexBridge 内部会根据QUASAR_TARGET在browserFirefox与chrome命名空间间自动切换见 bex-bridge.js。实战案例监听新标签页并通知 Quasar App下面完整演示浏览器打开新标签页 → 后台脚本感知 → Quasar App 收到事件的链路。这是后台脚本最常见的用法用浏览器扩展 API 监听事件再通过 bridge 把事件转发给应用。首先在后台脚本中监听标签页更新事件并向 Quasar App 发送自定义事件/** * Importing the file below initializes the extension background. * * Warnings: * 1. Do NOT remove the import statement below. It is required for the extension to work. * If you dont need createBridge(), leave it as import #q-app/bex/background. * 2. Do NOT import this file in multiple background scripts. Only in one! * 3. Import it in your background service worker (if available for your target browser). */ import { createBridge } from #q-app/bex/background const bridge createBridge({ debug: false }) chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) { if (bridge.portList.includes(app)) { bridge.send({ event: bex.tab.updated, to: app, payload: { url: tab.url } }) } })bridge.portList.includes(app)用于确认 Quasar App 的端口当前已连接popup / options / devtools 页面在 bridge 中的端口名统一为app避免向不存在的接收方发送消息。然后在 Quasar App 的组件生命周期钩子中监听该事件import { useQuasar } from quasar import { onBeforeUnmount } from vue export default { setup() { const $q useQuasar() // Our function which receives the URL sent by the background script. function doOnTabOpened({ payload }) { console.log(Browser tab updated:, payload.url) } // Add our listener $q.bex.on(bex.tab.updated, doOnTabOpened) // Dont forget to clean it up onBeforeUnmount(() { $q.bex.off(bex.tab.updated, doOnTabOpened) }) return {} } }注意两个配套动作$q.bex是 Quasar 在应用侧暴露的 bridge 实例由useQuasar()获取其portName固定为app而onBeforeUnmount中的off是必须的清理步骤——后台脚本可能长驻运行应用组件销毁后若不移除监听器会造成事件泄漏与重复回调。浏览器扩展 API 还暴露了大量其他事件chrome.tabs.onCreated、chrome.webNavigation、chrome.runtime.onInstalled等具体以你所面向的浏览器与 manifest 版本的官方文档为准。项目模板中的后台脚本也内置了若干参考实现如storage.get/set/remove、getTime事件可作为后续扩展的起点见 JS 模板 与 TS 模板。深入桥通信send / on / off 与端口模型后台脚本与 App、内容脚本的通信完全建立在 BexBridge 之上。它是一个Promise 化的事件系统实现见 bex-bridge.js每个上下文持有自己的 bridge 实例端口名规则为background、app、content脚本相对路径-实例号。后台脚本侧最常用的 API 组合// 监听来自 App / 内容脚本的消息可同步或异步返回响应 bridge.on(getTime, () Date.now()) // 向指定端口发送消息返回 Promise响应 bridge.send({ event: test, to: app, payload: { banner: Hello from background! } }).then(responsePayload { ... }).catch(err { ... }) // 广播给所有已连接的 App 与内容脚本 bridge.portList.forEach(portName { bridge.send({ event: test, to: portName, payload: Hello from background! }) }) // 找到任意已连接的内容脚本并发送 const contentPort bridge.portList.find(name name.startsWith(content)) if (contentPort) { bridge.send({ event: test, to: contentPort, payload: Hello from background! }) } // 监听端口连接 / 断开quasar:ports 为桥自动注册的内部事件 bridge.on(quasar:ports, ({ portList, added, removed }) { console.log(Ports:, portList) })关于消息体积有两个重要约束详见 BEX Bridge 文档大消息需分块浏览器对扩展消息有硬性大小限制。当payload为数组时bridge 会自动把每个元素作为独立消息分块发送若你本意是发送一个数组请把它包进对象里payload: { myArray: [...] }否则性能会很差。计算大小时还要算上 bridge 消息外壳本身的字节数。异步响应bridge.on的回调可以返回普通值同步响应、async函数或Promise异步响应send()一侧通过 Promise 等待结果。Manifest v3 下的后台脚本生命周期与自动重连这是后台脚本开发最容易踩坑的地方。在 Manifest v3 中Chrome 将后台脚本作为Service Worker运行浏览器会在其空闲约 30 秒后将其终止Firefox 在 MV3 下目前使用事件页机制行为类似所有桥连接会随之一同断开后台脚本内存中的状态也会全部丢失。扩展商店不允许通过keep-alive手段阻止终止因此 Quasar 的 bridge 选择透明地处理这一情况对应文档标注quasar/app-vite v3.8.1其源码与测试均验证了以下行为重启唤醒后台脚本每次重新启动时会广播一条一次性消息源码中的reviveSignature quasar:bex:revive见 bex-bridge.js要求之前连接过的 App 与内容脚本桥重新建立端口连接见 bex-bridge.js。自动重连若已连接的 App/内容脚本桥断线其下一次bridge.send()会先自动重连重连会唤醒后台脚本而不是直接 reject见 bex-bridge.js。端口等待send()目标端口尚未注册时会等待最多1 秒源码常量waitForPortTimeout 1000再失败覆盖后台重启后端口重新注册的窗口期。显式断开即退出自动重连通过bridge.disconnectFromBackground()主动断开的桥不再参与上述恢复机制。这些行为都有对应的单元测试覆盖例如background restart revives previously connected clients、send() transparently reconnects after the background is gone等用例见 bex-bridge.test.js。[!TIP] 后台脚本每次终止都会清空内存状态。任何需要跨重启存活的数据如登录态、偏好设置请用chrome.storage持久化不要依赖普通变量。调试与安全实践开启调试消息不通时可为相关桥开启 debug 模式通信过程会输出到浏览器控制台// Dynamically set debug mode bridge.setDebug(true) // boolean // Log a message on the console (if debug is enabled) bridge.log(Hello world!) // Log a warning on the console (regardless of the debug setting) bridge.warn(Hello world!, { some: data })log仅在 debug 开启时输出warn无条件输出二者都支持多参数。安全提示桥的每条消息都应视为不可信输入——尤其是来自内容脚本它可接触任意网页的消息。在使用扩展权限或读取存储数据之前务必校验事件名、发送方message.from、payload 结构、URL 与标识符暴露窄化的操作接口而非通用的高权限命令并按最小权限原则申请 manifest 权限与主机访问权。小结后台脚本是 Quasar BEX 的事件中枢与桥通信中心。回顾全文的关键结论在/src-bex/manifest.json中用chrome.background.service_workerMV3 单脚本与firefox.background.scripts多脚本注册后台脚本TS 扩展名由 Quasar CLI 在构建期自动转换bex-utils.js。通过import { createBridge } from #q-app/bex/background初始化桥注意只能在一个后台脚本中创建单例保护见 background.js。用chrome.*事件监听 bridge.send()把浏览器事件推给to: app在 Quasar App 中用$q.bex.on()/off()接收并清理。MV3 下后台脚本约 30 秒空闲即被终止bridge 已内置重启唤醒 自动重连 1 秒端口等待机制但内存状态仍需chrome.storage持久化。继续阅读系列文档可深入 内容脚本Content Scripts、BEX 配置项 与 TypeScript 支持。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/17 16:32:47

Page Assist:用本地模型和任意网页聊天的浏览器扩展

Page Assist:用本地模型和任意网页聊天的浏览器扩展 【免费下载链接】page-assist Use your locally running AI models to assist you in your web browsing 项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist Page Assist 是一款开源浏览器扩…

2026/11/10 14:06:44

三步跑通 GetQzonehistory:把 QQ 空间历史说说完整导出的指南

三步跑通 GetQzonehistory:把 QQ 空间历史说说完整导出的指南 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory GetQzonehistory 是一个 Python 工具,帮你登录自己…

2026/11/14 2:11:06

2026年AIGC论文降重工具评测与使用指南

1. 毕业论文降重工具现状解析2026年的学术环境中,论文降重已成为毕业生必经的考验。随着检测算法不断升级,传统"同义词替换语序调整"的降重方式已难以应对查重系统的语义分析能力。目前主流降重工具可分为三类:基础改写类&#xff…

2026/11/19 2:30:26

有电工证去富士康怎么考?官方报名入口在这儿,别再走弯路了

有电工证去富士康怎么考?官方报名入口在这儿,别再走弯路了 你是不是也遇到过这种情况:手里攥着电工证,但去富士康面试时却被告知“证过期了”?别急,这不是你一个人的难题,这正是当下很多特种作业人员面临的痛点—— 急需特种作业证才能上岗找工作…

2026/11/19 2:30:26

嘉兴高压电工证报名费2026河南最新政策怎么影响你找工作

嘉兴高压电工证报名费2026河南最新政策怎么影响你找工作 你是不是正在为找不到工作发愁?特种作业证没拿到,企业根本不会考虑你。特别是像嘉兴高压电工证这样的证书,几乎是电工行业的“敲门砖”。2026年河南最新政策对电工证的要求更加严格,报名费…

2026/11/19 2:30:26

低压电工证机构查询多少钱?外省证书能转过来吗?

低压电工证机构查询多少钱?外省证书能转过来吗? 之前考的证在外省能不能转过来?这几乎是所有想考证的人都会问的问题。特别是像低压电工证这类高需求的证书,很多在外地工作的人想把之前拿到的证“迁”过来,却又担心流程复杂、费用高、流程不清。其实,…

2026/11/19 2:25:26

临沂高压电工证考试在哪考?怕考不过白交培训费的看这篇

临沂高压电工证考试在哪考?怕考不过白交培训费的看这篇 怕考不过白交培训费?临沂高压电工证考试报名前,90%的人都踩过这些坑。现在你还在犹豫“在哪考”?别再盲目找培训机构了,下面这些干货,能帮你避开90%的坑。…

2026/11/18 21:12:58

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/18 21:55:23

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/19 0:04:42

深圳电工证培训考场模拟考试题库:郑州报考避坑指南

深圳电工证培训考场模拟考试题库:郑州报考避坑指南 证书过期了不知道怎么复审延期,很多人在遇到这个问题的时候才意识到特种作业证的重要性。其实,不管是电工证、焊工证还是高处作业证,这些证书不仅是上岗的“通行证”,更是法律对安全操作的硬性要求。尤…

2026/11/19 0:04:42

天津电工证查询入口多少钱能报上名

天津电工证查询入口多少钱能报上名 学历不高怕报不上名?别急,天津电工证查询入口其实没你想的那么难。今天咱们就来聊聊,怎么用最低的门槛、最少的钱,把电工证拿下来,还能查得到、用得上。 电工证到底值不值?先搞清楚它的作用…

2026/11/18 12:37:05

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/18 1:15:04

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑