|
|
1 month ago | |
|---|---|---|
| .github/workflows | 1 month ago | |
| docs | 1 month ago | |
| packages | 1 month ago | |
| scripts | 1 month ago | |
| src | 1 month ago | |
| tests | 1 month ago | |
| .editorconfig | 1 month ago | |
| .gitattributes | 1 month ago | |
| .gitignore | 1 month ago | |
| .npmrc | 1 month ago | |
| .prettierignore | 1 month ago | |
| .prettierrc.json | 1 month ago | |
| AGENTS.md | 1 month ago | |
| LICENSE | 1 month ago | |
| README.md | 1 month ago | |
| app.config.json | 1 month ago | |
| electron-builder.config.cjs | 1 month ago | |
| electron.vite.config.ts | 1 month ago | |
| eslint.config.mjs | 1 month ago | |
| package.json | 1 month ago | |
| playwright.config.ts | 1 month ago | |
| playwright.packaged.config.ts | 1 month ago | |
| pnpm-lock.yaml | 1 month ago | |
| pnpm-workspace.yaml | 1 month ago | |
| tsconfig.base.json | 1 month ago | |
| tsconfig.json | 1 month ago | |
| tsconfig.node.json | 1 month ago | |
| tsconfig.web.json | 1 month ago | |
| vitest.config.ts | 1 month ago | |
| vitest.native.config.ts | 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。新实现没有复制原应用源码、品牌资源或凭据。
