lean-electron-vue README

README проекта с github.com/mrcen3204097569-spec/lean-electron-vue. Одним файлом markdown: README.md.

lean-electron-vue

开箱即用的 Vite + Electron + Vue 3 + TypeScript 桌面应用开发模板

License: MIT Electron Vite Vue TypeScript

简体中文 | English

简介

一个不依赖 electron-vite、vite-plugin-electron 等第三方集成方案的现代化企业级 Electron 模板:通过两个很薄的自定义 Vite 插件把 Vite 和 Electron 串起来,整个构建流程只有几十行代码,看得懂、改得动。同时具备媲美 VS Code / Obsidian 的高扩展性插件生态系统与包含 50+ 丰富实用特性的全功能开发/生产力工作台。

🌟 50+ 核心特性与功能矩阵

🛠️ 1. 开发者全能工具箱矩阵 (Developer Toolbox Suite - 15+ 项)

🖥️ 2. 桌面视窗与原生 Shell 深度操控套件 (12+ 项)

🧩 3. 插件化架构与治理中心 (Plugin Engine Suite - 10+ 项)

🚀 4. 精选生产力与生活工作流插件生态 (已内置 10 款插件)

💎 5. 现代化桌面交互与系统体验 (8+ 项)

技术栈

分类 选型
桌面框架 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

快速开始

环境要求

安装与运行

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) 注册即可,用户可在「插件扩展中心」热启用或停用。

自动更新

  1. 修改 config/build.config.mts 中的 publish.url 为你的更新服务器地址。生产环境必须使用 HTTPS:latest*.yml 和安装包走明文 HTTP 时,中间人可以替换更新说明和安装包。配置里的 http://127.0.0.1 只用于本机调试。updateMsg 是纯文本(保留换行),弹窗不会把它当 HTML 渲染
  2. 提升 package.json 中的 version,执行 pnpm dist
  3. 把 release/ 目录下的安装包、.blockmap 和 latest*.yml 上传到更新服务器
  4. 旧版本应用启动时会自动检查更新,并弹出 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()

安全约束:

新增页面 / 接口

应用信息与图标

在 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 桥头的小屁孩

lean-electron-vue (mrcen3204097569-spec/lean-electron-vue)

Ищем в базе…

Что это такое?Легковесный шаблон десктопного приложения, сочетающий Vite, Electron, Vue 3 и TypeScript, созданный без использования сторонних инструментов интеграции, таких как electron-vite или vite-plugin-electron.
Это библиотека, которую я импортирую, или шаблон, на основе которого я строю проект?Это шаблон проекта, который вы клонируете и дорабатываете, а не библиотека для установки. Он связывает Vite и Electron между собой с помощью двух небольших собственных плагинов Vite, а не готового инструмента интеграции.
Как его запустить?Выполните 'pnpm dev', чтобы запустить сервер разработки Vite, который компилирует главный процесс через esbuild и автоматически запускает Electron с HMR для рендерера. Выполните 'pnpm build', чтобы собрать рендерер, скомпилировать главный процесс и вызвать electron-builder для создания установщика.
Какие версии Node и менеджера пакетов нужны?Node.js ^20.19.0 или >=22.12.0 (рекомендуется 22 LTS или новее) и pnpm 10, желательно включённый через corepack.
Какие подводные камни при установке стоит ожидать?При первом запуске 'pnpm dev' процесс может надолго зависнуть, потому что бинарный файл Electron загружается при первом запуске; рекомендуется настроить зеркало или прокси, особенно при медленном интернете. Также код главного процесса компилируется только один раз при старте разработки, поэтому после изменений в нём нужно перезапустить 'pnpm dev'.
Может ли electron-builder собирать пакеты для Windows, macOS и Linux?Да, он использует electron-builder, который поддерживает создание установщиков для всех трёх платформ; в конфигурационном файле есть раздел NSIS, предназначенный специально для установщика Windows.
Есть ли автообновление из коробки?Да, оно построено на electron-updater и включает встроенное окно обновления (проверка, прогресс загрузки, установка). Вы задаёте URL публикации, повышаете версию приложения, собираете проект и загружаете установщик вместе с файлами .blockmap и latest.yml на ваш сервер обновлений.
Как обрабатываются несколько окон и дочерние окна?Главный процесс перехватывает все вызовы window.open; рендерер может передать конфигурацию окна и выбрать, подключать ли встроенный preload-скрипт, так как произвольные пути к preload-скриптам из соображений безопасности не допускаются.
Какой стек для интерфейса настроен заранее?Element Plus с автоимпортом по требованию, а также автоматически импортируемые API Vue, Vue Router и Pinia; стили выполнены на Sass и animate.css, проверка типов через vue-tsc.
Почему автор избегает node_modules в финальной сборке?Все зависимости находятся в devDependencies: рендерер собирается Vite, а главный процесс (включая electron-updater) собирается esbuild в один файл mainEntry.js, поэтому установщик поставляется без node_modules и получается меньше по размеру.
Размер
0.8 MB
Звёзды
204
Обновлён
КоммитOct 31
Возраст
27 д
Коммиты · 90 дней