@neosjs/electron-core
开箱即用的 Electron 框架内核(monorepo neosjs-electron-template 的主发布物):主进程编排、preload 安全桥、跨端 IPC 契约、utilityProcess worker 与渲染端 SDK。你的应用主进程只需一份 defineConfig() 声明式配置,窗口、IPC、日志、持久化、更新、数据库等能力由框架托管;仓库内的 playground 是消费该内核的完整示例应用(Vue3 MPA 渲染端、数据域、设置 / 更新窗口、E2E 冒烟)。
系统要求(与仓库当前 package.json 一致)
Node.js >= 24.12、Electron >= 45、electron-builder >= 27、electron-updater >= 7。包级最低要求为 Electron >= 30(主进程 ESM)、Node >= 20.11。
安装
pnpm add @neosjs/electron-corenpm i @neosjs/electron-coreyarn add @neosjs/electron-core同时安装开发依赖:
pnpm add -D electron electron-vite安装后需为原生依赖做 Electron ABI 重建(better-sqlite3 必需,sharp 为 N-API 跨 ABI 兼容、无需重建):
npx electron-builder install-app-deps
# 或只重建涉及的原生模块
npx @electron/rebuild -f -o better-sqlite3快速上手
应用主进程的全部代码只有一份声明式配置:
// src/main/index.ts
import { defineConfig, startApp } from '@neosjs/electron-core'
startApp(defineConfig({
/* ── 身份(必填)──────────────────────────────── */
appId: 'com.neosjs.app', // 反向域名:win AppUserModelId / mac 签名命名空间
productName: 'NeosJS', // 产品短名:日志 service、菜单首项、关于窗标题
author: { name: 'NeosJS', email: 'dev@neosjs.com' },
homepage: 'https://neosjs.com', // 官网首页(菜单「官网」等外链单一来源)
/* ── 自定义协议(必填三字段)──────────────────── */
protocols: ['neos', 'neos-open'], // registerSchemesAsPrivileged 注册清单
internalProtocol: 'neos', // 内部协议:渲染页静态服务 + 窗口内导航信号
externalProtocol: 'neos-open', // 对外协议:系统级 deep-link
/* ── 更新与分发(必填)────────────────────────── */
updaterApiUrl: 'https://updater.neosjs.com', // 更新策略服务器基址
downloadUrl: 'https://neosjs.com/download', // 架构不匹配提示里的官网下载源
/* ── 可选项(均有缺省)────────────────────────── */
// env: 'production', // development/test/production/pre-release/release;缺省按生产对待
// loggerRedact: ['token', 'user.email'], // 日志脱敏字段
features: { updater: true, screenshot: false }, // 能力域开关,未列出的走智能默认
storeDefaults: {
general: { theme: 'dark' }
}, // store 默认值深合并
windows: {
main: { width: 1440 }
}, // 命名窗口创建选项覆盖(浅合并)
locales: {
'zh-CN': {
home: { title: '首页' }
}
} // 主进程文案深合并覆盖
}))另两端的最小用法:
// src/preload/index.ts —— 框架桥 + 应用自有桥组合
import { exposePreloadApi } from '@neosjs/electron-core/preload'
exposePreloadApi() // 暴露 window.neosApi / 日志桥 / 设备与应用身份// 渲染端(任意框架可用;Vue 用户另从 /renderer/vue 取 composables)
import { workerClient } from '@neosjs/electron-core/renderer'
await workerClient.run('image.resize', { src, width, destDir })能力域与包导出
内核能力
| 域 | 能力 |
|---|---|
| 窗口 | MPA 多窗口管理、启动画面交棒、macOS 红叉隐藏、窗口上限与选项覆盖 |
| IPC | 信封协议 + 来源校验 + 注册面/暴露面双向对账,17 个内置域(store、theme、locale、menu、shortcut、updater、downloader、screenshot、archive、database、server、system、storage、worker、file、log、app) |
| 日志 | pino 落盘轮转 + 渲染端批量上报(预算限流/紧急直发)+ worker 日志转发,统一脱敏 |
| 持久化 | electron-store 命名空间化(渲染端白名单沙盒)+ storeDefaults 可扩展默认值 |
| 多语言 | i18next 主进程文案 + vue-i18n 渲染端文案单一来源,locales 深合并覆盖 |
| 更新 | electron-updater 全托管:策略接口灰度/强更/feed 切换 |
| worker | utilityProcess 池:懒启动、ready 握手、崩溃自愈、风暴保护、MessagePort 页面直连 |
| 安全 | contextIsolation、sandbox 强制、CSP 双保险、特权协议 404 面、deep-link 白名单、路径纵深防御 |
| 数据库 | better-sqlite3 封装:迁移框架、慢查询监控、流式管道(背压熔断)、应用模块注入(dbModule) |
features 开关
内核分两层:内壳(app、window、ipc、log、store、locale、theme、menu、file)不可关;能力域可开关,未启用的域不注册 IPC handler、不进启动链(注册面裁剪即攻击面收敛,例如 screenshot: false 后 sharp worker 永不拉起)。
- 智能默认:重依赖域默认关、轻域默认开、声明
dbModule时database自动启用; database、updater、screenshot、archive、server默认关;worker、downloader、storage、system、shortcut默认开;- preload 桥对被禁域保留键面、方法替换为本地报错桩,调用得到「能力域 xxx 未启用」的明确错误。
包导出
| 子路径 | 内容 |
|---|---|
. | defineConfig、startApp、getDbApi(应用主进程 API) |
/preload | exposePreloadApi()(应用 preload 入口组合框架桥) |
/renderer | clients × 6(纯 TS 渲染端 SDK,框架无关,React / 无框架渲染端均可消费) |
/renderer/vue | useLogger、useLocale、useTheme(Vue composables) |
/shared/* | 跨端契约(通道枚举、zod schema、类型),preload / 测试可直接消费 |
/workers | worker 任务清单与协议类型 |
主入口为 ESM(type: module,不支持 CJS 消费方);/preload 为 CJS(sandbox preload 只能按普通脚本加载)。
仓库内的兄弟包
monorepo 内四个框架包以 changesets fixed 组锁步发版,electron-core 对已拆出模块保留透传垫片,既有导入面不变:
@neosjs/local-server — 本地 HTTP 服务引擎
纯 Node 实现的本地 HTTP 服务:回环白名单监听 + 路由注册 + 静态挂载(穿越 / 符号链接 / 点文件防护)。自 electron-core 拆出,IPC 面与 userData 收口留在 core。
@neosjs/downloader — 下载引擎
纯 Node 多任务下载引擎:单文件状态机(重定向 / 断点续传 / 重试 / 进度节流)+ 并发管理器 + 渲染端选项收敛。自 electron-core 拆出,IPC 面留在 core。
@neosjs/utils — 跨端纯函数
零依赖、三端(主进程 / 渲染端 / Node)同构的纯函数工具:格式化 / URL 白名单 / 文件名收敛 / 通用类型。自 electron-core 的 @shared/utils 拆出。
打包与发布参考
playground 是应用工程侧的参考实现:electron-builder.ts(electron-builder 27)、resources/、scripts/(签名守卫 / 构建号 / 更新服务器 mock)与打包脚本,可照抄到自己的仓库接 CI。产物输出在 playground/release/<version>/,支持 macOS dmg(arm64)、Windows NSIS x64、Linux AppImage / deb / snap;测试包文件名带 -test 后缀并走独立更新源与 userData 隔离。框架包本身的发版轨道是 npm(pnpm changeset-publish 或 CI release-core.yml),桌面安装包不是本仓库的产物。