项目的 README,来自 github.com/mrcen3204097569-spec/lean-electron-vue。合并为一个 markdown 文件:README.md。
一个不依赖 electron-vite、vite-plugin-electron 等第三方集成方案的现代化企业级 Electron 模板:通过两个很薄的自定义 Vite 插件把 Vite 和 Electron 串起来,整个构建流程只有几十行代码,看得懂、改得动。同时具备媲美 VS Code / Obsidian 的高扩展性插件生态系统与包含 50+ 丰富实用特性的全功能开发/生产力工作台。
pnpm dev:启动 Vite 开发服务器,用 esbuild 编译主进程后自动拉起 Electron,开发服务器地址通过环境变量 VITE_DEV_SERVER_URL 传入。渲染进程支持 HMRpnpm build:构建渲染进程并编译主进程,产出可运行的 dist/,不调用 electron-builderpnpm dist:在 pnpm build 的基础上调用 electron-builder 生成安装包pnpm test:用 Vitest 跑全套单元测试(覆盖 IPC、窗口策略、工具箱算法、插件治理、生命周期等 12 个套件 41 项单测).txt 文件capturePage 产生快照并直接存入系统剪贴板setup / teardown 机制,支持动态卸载清理markdown-notebook):双栏即时渲染排版、快捷语法注入、字数行数统计、导出 Markdown 文件snippet-vault):多语言代码片段集中收藏、按语言过滤、关键词搜索、一键复制代码expense-tracker):收支流水记录、分类汇总、净结余自动计算与 JSON 报表导出habit-tracker):自律习惯打卡、连续坚持天数 (Streak) 统计、打卡热力方块矩阵canvas-sketch):轻量 HTML5 Canvas 自由画板、画笔粗细颜色调节、橡皮擦与导出 PNGstopwatch-timer):毫秒级秒表计时、支持分段计次 (Lap) 对比与耗时分析pomodoro-timer):科学番茄工作法、专注/休息倒计时、原生完成弹窗与累计时长统计clipboard-history):自动追踪与持久化剪贴板文本记录、模糊搜索与一键回写color-palette):Apple、Tailwind、Nord 精品现代色卡与 WCAG 可访问性对比度检测api-client):轻量极速的 HTTP / REST 接口演练场、请求头与响应体实时解析Ctrl+K):毫秒级模糊检索、全应用页面直达、系统级快捷功能触发Ctrl+/):内置现代化 Cheat Sheet 面板,清晰展示视窗与各插件快捷键CommandOrControl+Shift+Space 一键呼出/隐藏前台窗口| 分类 | 选型 |
|---|---|
| 桌面框架 | Electron · electron-builder · electron-updater |
| 构建工具 | Vite · esbuild(编译主进程) |
| 前端框架 | Vue 3 · Vue Router · Pinia |
| UI | Element Plus · animate.css · Sass |
| 工程化 | TypeScript · ESLint · Prettier · unplugin-auto-import · unplugin-vue-components |
^20.19.0 或 >=22.12.0(推荐 22 LTS 及以上)corepack enable 启用)git clone https://github.com/mrcen3204097569-spec/lean-electron-vue.git
cd lean-electron-vue
pnpm install
# 开发模式
pnpm dev
# 构建应用(dist/,不打安装包)
pnpm build
# 打包安装包(输出到 release/)
pnpm dist
# 单元测试
pnpm test
[!TIP] 国内网络加速:Electron 45 起会在首次运行时才下载 Electron 二进制,electron-builder 打包时也需要下载相关工具。网络不佳时可先设置镜像:
# macOS / Linux export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ # Windows PowerShell $env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" $env:ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
| 命令 | 说明 |
|---|---|
pnpm dev |
启动开发环境(Vite + Electron) |
pnpm build |
构建应用,不打安装包 |
pnpm dist |
构建并打包安装包到 release/ |
pnpm test |
运行 Vitest 单元测试 |
pnpm typecheck |
使用 vue-tsc 做类型检查 |
pnpm lint / pnpm lint:fix |
ESLint 检查 / 自动修复 |
pnpm format |
Prettier 格式化 |
GitHub Actions 在 push 和 pull request 上运行 pnpm lint、pnpm typecheck、pnpm test 和 pnpm build。Windows / macOS / Linux 安装包矩阵只在手动触发或推送 v* tag 时运行。
├── config/
│ └── build.config.mts # electron-builder 打包配置 & 更新文案
├── plugins/
│ ├── devPlugin.mts # 开发:监听主进程、启动 / 重启 Electron
│ ├── devElectron.mts # 开发:Electron 子进程的启动、重启和退出
│ ├── buildPlugin.mts # 构建:编译主进程、生成 package.json、调用 electron-builder
│ └── mainProcess.mts # esbuild 编译主进程 / preload 的公共逻辑
├── tests/ # Vitest 纯逻辑单测
├── .github/ # CI 与 Dependabot
├── public/ # 静态资源
├── src/
│ ├── main/ # 主进程
│ │ ├── mainEntry.ts # 主进程入口
│ │ ├── preload/ # 预加载脚本(*.preload.ts 会被自动编译)
│ │ └── use/
│ │ ├── CustomScheme.ts # app:// 自定义协议
│ │ ├── Updater.ts # 自动更新
│ │ ├── WindowManage.ts # 窗口控制 & 子窗口创建
│ │ └── LogManage.ts # 主进程日志转发到渲染进程控制台
│ └── renderer/ # 渲染进程(Vue 应用)
│ ├── api/ # axios 封装,modules/ 下的文件自动注册
│ ├── common/ # 常量、子窗口工具函数
│ ├── components/system/ # 标题栏、更新弹窗、窗口显示控制
│ ├── router/ # 路由,modules/*.router.ts 自动注册
│ ├── store/ # Pinia
│ ├── types/ # 类型声明(含 preload 暴露的 window API)
│ └── views/ # 页面
├── eslint.config.mjs
├── vite.config.mts
└── package.json
pnpm dev
└─ vite dev server 启动
└─ devPlugin: esbuild watch 编译 src/main → dist/
└─ 启动 electron dist/mainEntry.js
└─ 环境变量 VITE_DEV_SERVER_URL=http://127.0.0.1:5173
└─ 未打包时 loadURL 并打开开发者工具
└─ 主进程变更:重新编译并重启 Electron
└─ preload 变更:重新编译并刷新窗口
└─ 已打包时忽略该变量和额外命令行参数,加载 app://index.html
pnpm build
└─ vite build(渲染进程 → dist/)
└─ buildPlugin(closeBundle 钩子)
├─ esbuild 编译主进程 → dist/mainEntry.js
└─ 生成精简的 dist/package.json
pnpm dist
└─ 同上,并设置 ELECTRON_PACKAGE=1
├─ electron-builder 打包 → release/
└─ 把更新文案按 YAML 双引号标量追加写入 release/latest*.yml
所有依赖都放在 devDependencies 中:渲染进程代码由 Vite 打包,主进程代码(包括 electron-updater)由 esbuild 打包进 mainEntry.js,因此安装包里不需要 node_modules,体积更小。
渲染进程无法直接访问 Node / Electron API,需要在 src/main/preload/main.preload.ts 中通过 contextBridge 暴露:
// src/main/preload/main.preload.ts
contextBridge.exposeInMainWorld('electronWindowApi', {
maximizeWindow: () => ipcRenderer.invoke('maximize-window')
})
// src/main/use/WindowManage.ts
ipcMain.handle('maximize-window', () => win.maximize())
// 渲染进程中调用
window.electronWindowApi.maximizeWindow()
监听类 API 不把 IpcRendererEvent 传给渲染进程,并返回取消订阅函数,在 onUnmounted 里调用。通道名和接口定义在 src/shared/electronApi.ts,src/renderer/types/electronRender.d.ts 引用同一份类型。新增 API 时改这一处,并在 preload 里实现对应接口。
本模板内置轻量级纯 TypeScript 插件引擎,支持声明式与编程式两种扩展方式:
import { markRaw } from 'vue'
import { definePlugin } from '@/plugin/pluginManager'
import MyWidget from './MyWidget.vue'
import MyPageView from './MyPageView.vue'
import MySettingsView from './MySettingsView.vue'
export const myCustomPlugin = definePlugin({
metadata: {
id: 'my-custom-plugin',
name: '自定义演示插件',
version: '1.0.0',
description: '演示如何在模板中注册独立扩展',
author: 'Developer'
},
// 1. 专属配置组件 (Obsidian 风格)
settingsComponent: markRaw(MySettingsView),
// 2. 声明式扩展点
extensions: {
views: [
{
id: 'my-view',
path: '/plugins/my-page',
title: '插件独立页面',
component: markRaw(MyPageView),
inNavigation: true // 自动注入侧边栏
}
],
statusBarItems: [
{
id: 'my-status-item',
alignment: 'left',
component: markRaw(MyWidget) // 自动挂载至底部状态栏
}
],
headerActions: [
{
id: 'my-action',
title: '快捷功能',
action: () => alert('点击了插件快捷按钮')
}
],
commands: [
{
id: 'my-command.action',
title: '快速执行插件任务',
category: '演示插件',
shortcut: 'Ctrl+Shift+M',
action: () => console.log('执行插件指令')
}
]
},
// 3. 编程式生命周期
setup(ctx) {
// 插件独立隔离存储
ctx.storage.set('installedAt', Date.now())
// 跨插件事件订阅与广播
ctx.on('custom-event', (data) => console.log('收到事件:', data))
},
teardown(ctx) {
console.log('插件停用清理')
}
})
在 src/renderer/plugins/builtin/index.ts 中通过 pluginManager.register(myCustomPlugin) 注册即可,用户可在「插件扩展中心」热启用或停用。
config/build.config.mts 中的 publish.url 为你的更新服务器地址。生产环境必须使用 HTTPS:latest*.yml 和安装包走明文 HTTP 时,中间人可以替换更新说明和安装包。配置里的 http://127.0.0.1 只用于本机调试。updateMsg 是纯文本(保留换行),弹窗不会把它当 HTML 渲染package.json 中的 version,执行 pnpm distrelease/ 目录下的安装包、.blockmap 和 latest*.yml 上传到更新服务器SystemAppUpdate 更新弹窗开发环境下应用未打包,
electron-updater会跳过更新检查,这是正常现象。
import { createDialog, dialogReady } from '@/common/dialog'
// 父窗口
const win = await createDialog('/test', {
width: 800,
height: 600,
modal: true, // 父窗口是发起 window.open 的那个窗口
webPreferences: { preloadMain: true } as any // 是否注入主窗口的 preload
})
// 子窗口页面加载完成后通知父窗口
dialogReady()
安全约束:
webPreferences(包括 nodeIntegration、contextIsolation、sandbox、webviewTag 和 preload 路径)。只有 webPreferences.preloadMain === true 会注入内置 preload;否则子窗口加载一份空 preload,避免继承主窗口的特权脚本modal、标题等)。modal: true 时,父窗口固定为发起 window.open 的那个窗口app:// 以及当前开发服务器同源地址。http / https 外链用系统浏览器打开,其它协议直接拒绝will-navigate 和 will-redirect,页面不能再跳到不受信任的地址window.electronWindowApi 不存在而抛错window.open(url)、<a target="_blank"> 以及逗号形式的 features(例如 width=800,height=600)不会再让主进程 JSON.parse 抛错。left / top 按 x / y 处理,无法识别的字段会被忽略src/renderer/router/modules/ 下新建 xxx.router.ts 并默认导出路由配置,会被自动注册src/renderer/api/modules/ 下新建 xxx.ts 并默认导出接口对象,通过 api.xxx 调用在 config/build.config.mts 中修改 productName、appId、nsis 等配置。当前示例目标是 Windows nsis、macOS dmg、Linux AppImage。图标可参考 electron-builder 文档 放到 build/ 目录,或在配置中单独指定。应用持有单实例锁,第二次启动会把已有窗口还原到前台。
修改主进程代码后没有生效? pnpm dev 会监听 src/main。入口及其依赖变更后会重新编译并重启 Electron;*.preload.ts 变更后会重新编译并刷新窗口。如果进程没起来,看终端里的 esbuild 报错。
首次 pnpm dev 卡住很久? 多半是在下载 Electron 二进制,参考上面的镜像配置。
ESLint 报 ref / computed 等未定义? 这些 API 由 unplugin-auto-import 自动导入,对应的 .eslintrc-auto-import.json 会在运行 pnpm dev 后自动生成或更新。
MIT © 2023-present 桥头的小屁孩