You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
dash bbecf870d4 feat: migrate application settings and fix titlebar alignment 1 month ago
.github/workflows feat: complete template diagnostics and update foundations 1 month ago
docs feat: migrate application settings and fix titlebar alignment 1 month ago
packages feat: migrate application settings and fix titlebar alignment 1 month ago
scripts feat: complete template diagnostics and update foundations 1 month ago
src feat: migrate application settings and fix titlebar alignment 1 month ago
tests feat: migrate application settings and fix titlebar alignment 1 month ago
.editorconfig feat: initialize modular secure Electron Vue template 1 month ago
.gitattributes chore: keep template checkout line endings portable 1 month ago
.gitignore feat: initialize modular secure Electron Vue template 1 month ago
.npmrc feat: initialize modular secure Electron Vue template 1 month ago
.prettierignore feat: initialize modular secure Electron Vue template 1 month ago
.prettierrc.json feat: initialize modular secure Electron Vue template 1 month ago
AGENTS.md feat: migrate application settings and fix titlebar alignment 1 month ago
DESIGN.md feat: migrate application settings and fix titlebar alignment 1 month ago
LICENSE feat: initialize modular secure Electron Vue template 1 month ago
README.md feat: migrate application settings and fix titlebar alignment 1 month ago
app.config.json feat: complete template diagnostics and update foundations 1 month ago
design.tokens.json feat: seal M1 v0.1.0 modular Electron template 1 month ago
electron-builder.config.cjs feat: complete template diagnostics and update foundations 1 month ago
electron.vite.config.ts feat: initialize modular secure Electron Vue template 1 month ago
eslint.config.mjs feat: seal M1 v0.1.0 modular Electron template 1 month ago
package.json feat: complete template diagnostics and update foundations 1 month ago
playwright.config.ts feat: initialize modular secure Electron Vue template 1 month ago
playwright.packaged.config.ts feat: initialize modular secure Electron Vue template 1 month ago
pnpm-lock.yaml feat: seal M1 v0.1.0 modular Electron template 1 month ago
pnpm-workspace.yaml feat: add electron-trpc adapter with IPC communication 1 month ago
tsconfig.base.json feat: initialize modular secure Electron Vue template 1 month ago
tsconfig.json feat: initialize modular secure Electron Vue template 1 month ago
tsconfig.node.json feat: initialize modular secure Electron Vue template 1 month ago
tsconfig.web.json feat: initialize modular secure Electron Vue template 1 month ago
vitest.config.ts feat: initialize modular secure Electron Vue template 1 month ago
vitest.native.config.ts feat: initialize modular secure Electron Vue template 1 month ago

README.md

Electron Workshop

一个便于二次开发的 Electron + Vue 3 + TypeScript 模板。借鉴 Zephyr 的进程分层与 workspace 结构,重新实现基础能力;原项目保持独立。

模板的重点是:开发入口少、模块可替换、依赖单向、安全默认开启、资源有明确生命周期。

当前封板基线:M1 · v0.1.0。范围、维护规则与下一阶段验收条件见 项目里程碑。

M1 后已补充统一诊断上报与持续更新基础:设置页管理授权/导出,主进程持久化脱敏队列,安装版本自动检查但手动下载和安装。接收端约定见 日志与诊断,发版步骤见 发布与升级;默认地址为空,不连接模板作者服务器。

示例工作台:浅色主题

深色主题预览 · 设计规范 · Renderer 开发 · 能力裁剪 · 整体评估 · 本地验证记录

快速开始

需要 Node.js 22.13+(推荐 Node 22 LTS)和 pnpm 11.5.2。使用支持 Electron 图形窗口的桌面环境。

pnpm install
pnpm dev

不需要提前编译 workspace 包;electron-vite 直接处理源码。SQLite 13 使用随包提供的 Node-API 预构建文件;pnpm 不运行它的隐式 node-gyp,安装时由 electron-builder 检查原生依赖。首次安装会显式下载 Electron;遇到原生模块问题执行 pnpm rebuild。不在预构建覆盖范围内的平台可能需要 Python 和 C++ 构建工具。

共享依赖版本统一在 pnpm-workspace.yaml 的 catalog 中维护,各包使用 catalog: 声明自己的依赖。Zod、tRPC、Vue、Electron 与桌面运行库升级时只需修改该文件并执行 pnpm install。catalogs.peers 单独管理兼容范围,与实际安装的固定版本区分;本地包继续使用 workspace:*。

打包配置会将生产依赖中的 catalog: 解析成已安装的实际版本,并写入发布包的元数据,以兼容 electron-builder 的版本检查。

pnpm tokens            # 修改设计 token 后同步 CSS 和 DESIGN.md
pnpm lint              # token 一致性、ESLint 与关键异步规则
pnpm typecheck         # main/preload 与 renderer 分开检查
pnpm test              # 安全、配置、生命周期等单元测试
pnpm build             # 类型检查并构建
pnpm check             # lint → typecheck → test → build
pnpm test:e2e          # 真实 Electron 启动、数据持久化、隔离、跨窗口同步
pnpm package           # 当前系统的未安装应用目录
pnpm test:packaged     # 对已打包程序验证资源协议、桥接与原生 SQLite
pnpm dist              # 当前系统的安装包
pnpm release:check     # 校验正式发布的身份、版本、地址和签名配置
pnpm release:build     # 发布前检查并生成产物;不自动上传
pnpm format

Linux CI 的 Electron 测试使用 xvfb-run --auto-servernum pnpm test:e2e。无显示环境的 Linux 需要 Xvfb 与 Electron 系统库。不要通过 --no-sandbox 绕过安全默认值。

已保留的基础能力

能力 新实现
主进程 / preload / renderer 分层 electron-vite,renderer 没有 Node 权限
类型化 IPC、主进程事件 tRPC 11 + electron-trpc,query/mutation/subscription、共享 Zod 模型与 procedure 窗口权限
模块初始化与销毁 依赖排序、启动回滚、反向清理、显式 Scope
多窗口管理 main/settings/about 角色、单实例、尺寸恢复、导航限制
配置持久化 独立版本迁移、逐字段默认补齐与恢复、迁移备份、原子替换
JSON 键值数据 本地小数据存储、校验与原子写入
SQLite WAL、参数化 SQL、事务迁移、禁止数据库降级
文件选择、读写、目录列举 原生对话框、窗口专属授权句柄、大小限制
文件监听 限额、事件合并、窗口刷新与关闭自动撤销
原生确认与上下文菜单 固定可序列化结构,不接受 renderer 回调或任意 Electron options
外部链接 固定链接标识,HTTPS + 主机白名单
日志 electron-log,文件大小限制,不记录 IPC 参数或凭据
主题与国际化 system/light/dark,中英文,跨窗口同步
开机启动 安装后的 Windows/macOS 版本;开发版本不会注册 Electron
更新 按平台选择 updater,手动检查/下载/安装,默认无发布源
凭据 safeStorage 系统加密,仅主进程读取,Linux basic_text 不接受
浏览器 UI 包 小型 Vue 组件与统一样式,无额外构建前置步骤
工程交付 固定依赖、lockfile、三平台 CI、行为测试、模块生成与重命名脚本

JSON 存储使用小型原子存储。通信沿用 ai-friend 的 electron-trpc 思路,使用仓库内的 tRPC 11 适配版本,并补齐来源校验、订阅限额和监听清理;版本与维护范围见 适配器说明。AI 业务、Monaco、webview、脚本执行器和原有产品 UI 按需通过业务模块加入。扩展时参考 模块开发。

import { trpc } from '@/lib/trpc'

const notes = await trpc.notes.list.query()
await trpc.notes.add.mutate('Hello')
const subscription = trpc.settings.changed.subscribe(undefined, {
  onData: (settings) => console.log(settings.theme),
  onError: (error) => console.error(error.message)
})
// 在组件卸载或作用域结束时调用
subscription.unsubscribe()

一个 API 的权限、输入、输出和执行入口集中在主进程所属模块;procedure 直接调用业务服务。contracts 只保存共享模型,renderer 通过类型导入 AppRouter 获得完整客户端推导。新增简单接口不再维护三套路由清单。

目录

packages/
  contracts/   共享数据模型与 schema,不定义 API 路由
  electron-trpc/ tRPC 11 IPC 传输适配,main / preload / renderer 独立入口
  core/        Node 基础工具;不依赖 Electron 或应用
  desktop/     Electron、SQLite、文件、更新和凭据适配器
  ui/          纯 Vue 展示组件
src/
  main/        模块内定义 tRPC procedure,trpc/ 提供公共机制与应用组装
  preload/     固定 electron-trpc 通道桥接;不暴露原生 IPC
  renderer/    Vue、Pinia、router、i18n 与能力示例
scripts/       重命名与模块生成
tests/         单元测试与真实 Electron 测试
docs/          架构、扩展、安全和发布说明

依赖方向与设计理由见 架构。新增功能:声明契约 → 组合 tRPC 路由 → 注册业务模块 → renderer 调用;pnpm module:new 自动完成前三步。

从模板创建应用

pnpm rename my-desktop "My Desktop" com.example.desktop
pnpm install
pnpm module:new greeting
pnpm format
pnpm check

app.config.json 是产品名、应用 ID、固定外部链接和更新源的唯一配置入口。重命名脚本同步 package.json 与 HTML title。侧栏 Workshop 视觉标识是示例 UI,可以自行替换。

开发数据在系统 appData 下的 <name>-dev,正式数据在 Electron userData 中,二者隔离。数据库在 data/app.sqlite,配置在 settings.json,加密凭据在 credentials.json。模板不提供 renderer 任意修改数据目录的能力;迁移数据目录必须作为主进程专用流程设计。更改应用名称或 ID 前请规划已有用户数据迁移。

应用配置升级保留合法用户值,支持嵌套字段补齐;重命名或类型改变通过应用自己的连续版本迁移处理。旧配置自动转换并备份,旧程序拒绝写入较新版本的配置。详见 配置升级。

主进程启动参数 --profile-dir=<absolute-path> 可选择独立数据目录,适用于测试或便携使用;它不会迁移已有数据,renderer 不能修改这个参数。打包测试使用临时目录,结束后清理。

安全和发布

默认不加载远程网页、不暴露 raw IPC、不提供任意文件路径或命令执行接口。生产页面通过 app://desktop 加载并限制 CSP;打包版本关闭 Node 调试与 RunAsNode 等 fuses。权限和威胁边界见 安全设计。

默认更新源为空,不会访问原项目的服务器。配置发布前阅读 发布与更新,设置自己的 HTTPS feed、平台签名与发布凭据。

MIT License。新实现没有复制原应用源码、品牌资源或凭据。