Skip to content

@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。

安装 ​

sh
pnpm add @neosjs/electron-core
sh
npm i @neosjs/electron-core
sh
yarn add @neosjs/electron-core

同时安装开发依赖:

sh
pnpm add -D electron electron-vite

安装后需为原生依赖做 Electron ABI 重建(better-sqlite3 必需,sharp 为 N-API 跨 ABI 兼容、无需重建):

sh
npx electron-builder install-app-deps
# 或只重建涉及的原生模块
npx @electron/rebuild -f -o better-sqlite3

快速上手 ​

应用主进程的全部代码只有一份声明式配置:

ts
// 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: '首页' }
    }
  } // 主进程文案深合并覆盖
}))

另两端的最小用法:

ts
// src/preload/index.ts —— 框架桥 + 应用自有桥组合
import { exposePreloadApi } from '@neosjs/electron-core/preload'

exposePreloadApi() // 暴露 window.neosApi / 日志桥 / 设备与应用身份
ts
// 渲染端(任意框架可用;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 切换
workerutilityProcess 池:懒启动、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)
/preloadexposePreloadApi()(应用 preload 入口组合框架桥)
/rendererclients × 6(纯 TS 渲染端 SDK,框架无关,React / 无框架渲染端均可消费)
/renderer/vueuseLogger、useLocale、useTheme(Vue composables)
/shared/*跨端契约(通道枚举、zod schema、类型),preload / 测试可直接消费
/workersworker 任务清单与协议类型

主入口为 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),桌面安装包不是本仓库的产物。