Electron ServiceWorkers API在主进程掌握 Service Worker 的运行状态、日志与通信【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electronsession.serviceWorkers是 Electron 提供给主进程Main Process的 API用于查询某个会话中所有正在运行的 Service Worker、监听其控制台日志与注册/生命周期事件并通过ServiceWorkerMain实例与 Worker 进程直接进行 IPC 通信。读完本文你将能够完整掌握ServiceWorkers类的全部事件与方法、理解其在 源码 中如何挂接 Chromium 的content::ServiceWorkerContext观察者并学会在应用启动时为已注册的 Worker 主动启动并下发消息。一、定位与获取方式Session的serviceWorkers属性ServiceWorkers类不直接从electron模块导出它只能作为其他 API 方法的返回值获得。获取它的唯一入口是Session实例的serviceWorkers属性const { session } require(electron) // 获取所有正在运行的 service worker console.log(session.defaultSession.serviceWorkers.getAllRunning()) // 监听控制台日志并获取发送日志的 worker 信息 session.defaultSession.serviceWorkers.on(console-message, (event, messageDetails) { console.log( Got service worker message, messageDetails, from, session.defaultSession.serviceWorkers.getFromVersionID(messageDetails.versionId) ) })从源码可以确认这一绑定关系Session的 JS 绑定在 electron_api_session.cc 中通过.SetProperty(serviceWorkers, Session::ServiceWorkerContext)注册其实现会懒创建并缓存一个ServiceWorkerContext对象。值得注意的是ServiceWorkerContext构造时还会把会话对应的存储分区配置登记进BrowsingDataRemover的数据类型列表DATA_TYPE_SERVICE_WORKERS因此session.clearStorageData()同样能清理已注册的 Service Worker——这一点在 测试用例 中被明确使用每次用例前后都调用ses.clearStorageData()以保证隔离。ServiceWorkerContext与底层的关系也很直接其构造函数从ElectronBrowserContext的默认存储分区取出content::ServiceWorkerContext并调用AddObserver(this)注册自己析构时移除观察者。这意味着ServiceWorkers的全部事件与方法本质都是对 Chromium 内容层 Service Worker 基础设施的封装。二、ServiceWorkerInfo每个 Worker 版本的描述对象ServiceWorkers的多个方法都会返回ServiceWorkerInfo对象结构定义见 service-worker-info.md字段类型说明scriptUrlstring该 Service Worker 运行的脚本的完整 URLscopestring该 Service Worker 生效的基准 URLrenderProcessIdnumber该 Worker 所在进程的虚拟 ID非操作系统 PID与webContents.getProcessId()使用同一套 ID 体系versionIdnumber该 Service Worker 版本的 ID在实现层scriptUrl、scope、renderProcessId由ServiceWorkerRunningInfoToDict从content::ServiceWorkerRunningInfo直接组装见 electron_api_service_worker_context.cc#L68-L76。三、实例事件Event:console-message当某个 Service Worker 向控制台输出内容时发出回调参数为eventEventmessageDetailsObjectmessagestring - 实际的控制台消息文本versionIdnumber - 发送日志的 Service Worker 的版本 IDsourcestring - 消息来源类型可能为javascript、xml、network、console-api、storage、rendering、security、deprecation、worker、violation、intervention、recommendation或otherlevelnumber - 日志级别0~3依次对应verbose、info、warning、errorsourceUrlstring - 消息来源的 URLlineNumbernumber - 触发该消息的源码行号source字段的字符串映射在 MessageSourceToString 中逐一对应 Blink 的ConsoleMessageSource枚举level则是直接把message.message_level转成int32_t后透出。spec/api-service-workers-spec.ts#L77-L96 验证了级别映射console.log/info为 1warn为 2error为 3且来源均为console-api。Event:registration-completed当 Service Worker 注册成功时发出可能发生在navigator.serviceWorker.register(/sw.js)成功 resolve 之后也可能发生在 Chrome 扩展加载时。回调参数eventEventdetailsObjectscopestring - 该 Service Worker 注册的基准 URLEvent:running-status-changedExperimental当某个 Service Worker 的运行状态变化时发出。回调参数detailsversionIdnumber - 状态发生变化的 Service Worker 版本 IDrunningStatusstring - 运行状态可能为starting、running、stopping、stopped从源码结构看这个事件是四个 Chromium 生命周期回调的统一出口OnVersionStartingRunning/OnVersionStartedRunning/OnVersionStoppingRunning/OnVersionStoppedRunning分别转调OnRunningStatusChanged后者先通知对应ServiceWorkerMain实例再向 JS 侧发射事件见 electron_api_service_worker_context.cc#L99-L162。四、实例方法serviceWorkers.getAllRunning()返回Recordnumber, ServiceWorkerInfo—— 键为 Service Worker 版本 ID、值为对应信息的对象。底层直接遍历content::ServiceWorkerContext::GetRunningServiceWorkerInfos()返回的flat_map逐个版本组装字典GetAllRunningWorkerInfo。没有任何 Worker 运行时返回空对象{}这一点在 spec/api-service-workers-spec.ts#L52-L54 中得到验证。serviceWorkers.getInfoFromVersionID(versionId)versionIdnumber - Service Worker 版本 ID返回ServiceWorkerInfo。若该 Worker 不存在或未运行方法会抛出异常源码中抛出Could not find service worker with that version_id。serviceWorkers.getFromVersionID(versionId)DeprecatedversionIdnumber - Service Worker 版本 ID返回ServiceWorkerInfo。若该 Worker 不存在或未运行则抛出异常。已弃用请改用getInfoFromVersionID。源码中GetFromVersionID会先发出弃用警告ServiceWorkersDeprecateGetFromVersionID然后委托给GetInfoFromVersionID见 electron_api_service_worker_context.cc#L198-L208。serviceWorkers.getWorkerFromVersionID(versionId)ExperimentalversionIdnumber - Service Worker 版本 ID返回ServiceWorkerMain | undefined—— 与该版本 ID 关联的 Service Worker 实例若没有对应版本或其运行状态已变为stopped则返回undefined。serviceWorkers.startWorkerForScope(scope)Experimentalscopestring - 要启动的 Service Worker 的 scope返回PromiseServiceWorkerMain—— Worker 启动后 resolve。若该 scope 的 Worker 已在运行则不做任何额外操作。底层调用content::ServiceWorkerContext::StartWorkerForScope以 scope 的一方 origin 构造StorageKey并异步等待结果StartWorkerForScope。典型实战场景应用启动时为所有已注册的 Worker 兜底启动并通过 IPC 通知其有窗口已创建const { app, session } require(electron) const { serviceWorkers } session.defaultSession // 收集所有 service worker 的 scope const workerScopes Object.values(serviceWorkers.getAllRunning()).map((info) info.scope) app.on(browser-window-created, async (event, window) { for (const scope of workerScopes) { try { // 确保 worker 已启动 const serviceWorker await serviceWorkers.startWorkerForScope(scope) serviceWorker.send(window-created, { windowId: window.id }) } catch (error) { console.error(Failed to start service worker for ${scope}) console.error(error) } } })五、ServiceWorkerMain与 Worker 进程通信的句柄startWorkerForScope与getWorkerFromVersionID返回的ServiceWorkerMain实例代表某个 scope 下脚本的某个具体版本详见 service-worker-main.md其成员同样为Experimental只读属性scopeWorker 的 scope URLscriptURLWorker 脚本 URLversionId该 scope 下脚本版本的 IDipc一个作用域限定到该 Worker 的IpcMainServiceWorker实例方法isDestroyed()Worker 版本是否已被销毁send(channel, ...args)通过channel向 Worker 进程发送异步消息参数按结构化克隆算法序列化与postMessage相同发送 Function、Promise、Symbol、WeakMap 或 WeakSet 会抛异常Worker 侧可用ipcRenderer监听同一channel接收startTask()发起一个任务以在end()被调用前保持 Worker 存活返回对象仅含end方法若从不调用endWorker 在空闲时也不会终止ServiceWorkerMain的 C 实现electron_api_service_worker_main.h透露了几个关键设计实例由browser_context_id storage_partition_config version_id三元组ServiceWorkerKey唯一标识保证不同会话/分区中相同 versionId 的 Worker 不会混淆对象在 cppgc 堆上通过SelfKeepAlive自持有生命周期与底层 Service Worker 版本对齐使得已注册的 IPC 处理器在整个存活期内都能正常分发通过 Mojo 关联远程对象mojom::ElectronRenderer与渲染进程建立连接来完成send通信并在状态变化时可能断开该连接。Worker 侧的回复通道由IpcMainServiceWorker提供详见 ipc-main-service-worker.md它是IpcMain的变体提供on、once、removeListener、removeAllListeners、handle、handleOnce、removeHandler等方法专用于主进程与 Service Worker 之间的send/invoke双向通信。相关端到端行为在 spec/api-service-worker-main-spec.ts 中有独立测试覆盖。六、内部实现与内部方法一览ServiceWorkerContext在 GetObjectTemplateBuilder 中除了注册文档列出的公开方法外还暴露了两个以下划线开头的内部方法未在公开文档中列出属于实现细节_getWorkerFromVersionIDIfExists(versionId)按ServiceWorkerKey查找已存在的ServiceWorkerMain找不到时不抛异常_stopAllWorkers()调用底层StopAllServiceWorkers停止该会话的所有 Worker返回 Promise。事件与状态同步的完整链路可以概括为content::ServiceWorkerContext观察者回调注册完成 / 控制台消息 / 状态变化 / 版本冗余触发ServiceWorkerContext对应方法控制台消息经OnReportConsoleMessage组装为versionId、source、level、message、lineNumber、sourceUrl后发出console-message事件状态变化经OnRunningStatusChanged更新ServiceWorkerMain后发出running-status-changed事件方法调用getAllRunning、getInfoFromVersionID等直接读取GetRunningServiceWorkerInfos()的内存快照。七、测试验证与使用前提spec/api-service-workers-spec.ts覆盖getAllRunning()初始为空、加载注册页后恰好一个、getFromVersionID()的scriptUrl/scope正确性、console-message的 source 与 level 映射spec/api-service-worker-main-spec.ts覆盖ServiceWorkerMain的实验性能力事件触发的前提是页面真实注册了 Service Worker如navigator.serviceWorker.register(/sw.js)且监听方需持有正确的Session实例——不同 partition 的会话各自独立。适用前提小结running-status-changed、getWorkerFromVersionID、startWorkerForScope及全部ServiceWorkerMain能力均为Experimental接口可能随版本演进调整getFromVersionID已弃用新代码应使用getInfoFromVersionIDgetInfoFromVersionID与getFromVersionID在目标 Worker 不存在或未运行时会抛异常生产代码中建议配合getAllRunning()的结果或try/catch做防御与 Worker 通信走结构化克隆函数等不可克隆值不能通过send传递。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考