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 26c24d2570 chore: keep template checkout line endings portable 1 month ago
.github/workflows feat: initialize modular secure Electron Vue template 1 month ago
docs feat: initialize modular secure Electron Vue template 1 month ago
packages feat: initialize modular secure Electron Vue template 1 month ago
scripts feat: initialize modular secure Electron Vue template 1 month ago
src feat: initialize modular secure Electron Vue template 1 month ago
tests feat: initialize modular secure Electron Vue template 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: initialize modular secure Electron Vue template 1 month ago
LICENSE feat: initialize modular secure Electron Vue template 1 month ago
README.md feat: initialize modular secure Electron Vue template 1 month ago
app.config.json feat: initialize modular secure Electron Vue template 1 month ago
electron-builder.config.cjs feat: initialize modular secure Electron Vue template 1 month ago
electron.vite.config.ts feat: initialize modular secure Electron Vue template 1 month ago
eslint.config.mjs feat: initialize modular secure Electron Vue template 1 month ago
package.json feat: initialize modular secure Electron Vue template 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: initialize modular secure Electron Vue template 1 month ago
pnpm-workspace.yaml feat: initialize modular secure Electron Vue template 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 结构,重新实现基础能力;原项目保持独立。

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

示例工作台:浅色主题

深色主题预览 · 本地验证记录

快速开始

需要 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 lint              # 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 format

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

已保留的基础能力

能力 新实现
主进程 / preload / renderer 分层 electron-vite,renderer 没有 Node 权限
类型化 IPC、主进程事件 共享 Zod 契约,统一请求路由、固定事件通道、窗口权限
模块初始化与销毁 依赖排序、启动回滚、反向清理、显式 Scope
多窗口管理 main/settings/about 角色、单实例、尺寸恢复、导航限制
配置持久化 JSON 默认合并、类型校验、损坏备份、原子替换
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 存储不再依赖 LowDB;类型化 IPC 不再依赖 tRPC fork。原有功能需求由更小的接口实现。AI 业务、Monaco、webview、脚本执行器和原有产品 UI 不属于基础默认依赖,按需通过业务模块加入。扩展时参考 模块开发。

目录

packages/
  contracts/   浏览器安全的 API / event / settings schema
  core/        Node 基础工具;不依赖 Electron 或应用
  desktop/     Electron、SQLite、文件、更新和凭据适配器
  ui/          纯 Vue 展示组件
src/
  main/        应用组合入口与业务模块
  preload/     能力桥接;只暴露 call / on
  renderer/    Vue、Pinia、router、i18n 与能力示例
scripts/       重命名与模块生成
tests/         单元测试与真实 Electron 测试
docs/          架构、扩展、安全和发布说明

依赖方向与设计理由见 架构。新增功能只需:声明契约 → 注册模块 → renderer 调用。

从模板创建应用

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。新实现没有复制原应用源码、品牌资源或凭据。