Electron Admin Template

一个基于 Electron + Vue 3 + TypeScript + Vite 的桌面管理模板，内置 Naive UI、Tailwind CSS、Pinia、Vue Router，并集成 Drizzle ORM + better-sqlite3 的本地数据库。包含登录窗口与主窗口切换、主题切换、动态菜单、状态持久化等常用管理台能力，适合作为 Electron 管理应用的起步工程。

项目地址：https://github.com/fengjun2022/electron-admin-template

技术栈

• Electron 30（多窗口：登录/主窗口）
• Vue 3 + TypeScript + Vite 7
• Vue Router（Hash 模式，适配 file://）
• Pinia + pinia-plugin-persistedstate（状态持久化）
• Naive UI（组件库）
• Tailwind CSS v4（@tailwindcss/postcss）
• Drizzle ORM + better-sqlite3（本地 SQLite）
• Iconify / Ionicons 图标

功能概览

• 登录/主窗口分离：electron/main.ts 管理窗口与切换（open-main-window、logout-to-login）。
• 主题与布局：暗/亮主题切换、头部/面包屑显示开关、侧边栏收起，均持久化保存（src/stores/global-store.ts）。
• 动态菜单：从路由动态生成侧边菜单（src/config/menu.ts + src/router）。
• 数据持久化：pinia-plugin-persistedstate 示例（stores/modules/counter.ts）。
• 本地数据库：自动建表与默认数据初始化，表结构与仓储封装（electron/db.ts、electron/schema.ts、electron/repository.ts）。
• 预加载桥接：在 preload 暴露 window.electronAPI（electron/preload.ts），渲染层通过 IPC 使用数据库能力。

目录结构

• electron/：主进程代码
  • main.ts：应用入口/窗口管理/IPC handlers
  • preload.ts：向渲染进程暴露 window.electronAPI
  • db.ts：初始化 SQLite、自动建表与默认配置
  • schema.ts：Drizzle ORM 表定义
  • repository.ts：数据访问封装（系统设置、模板）
• src/：渲染进程（Vue）
  • main.ts：应用挂载，注册 Pinia、Router、第三方插件
  • router/：路由定义（含 /login、/home、/tem）
  • layouts/：布局（头部、侧边栏、主内容、聊天侧边）
  • stores/：Pinia 全局与模块化 Store
  • config/：主题与菜单生成
  • views/：示例页面（首页、模板管理、登录）
• drizzle.config.ts：Drizzle CLI 配置
• vite.config.ts：Vite 配置（@ 指向 src）
• package.json：脚本与打包配置（electron-builder）

快速开始

环境要求

• Node.js 20+
• npm 9+（或使用 pnpm/yarn，自行换用命令）

安装依赖

npm install

如出现 better-sqlite3 版本/ABI 不匹配，可执行：

npm run rebuild

开发调试

• 启动开发模式（同时跑 Vite 与 Electron）：

npm run dev

• 按需自动打开 DevTools：
  • macOS/Linux: OPEN_DEVTOOLS=1 npm run dev
  • Windows (PowerShell): $env:OPEN_DEVTOOLS=1; npm run dev

说明：默认不自动打开 DevTools，避免无害的 Autofill 报错噪音（详见下文“DevTools 提示”）。

构建打包

npm run build

• 渲染进程构建产物：dist/
• 主进程构建产物：dist-electron/
• 安装包/应用产物：release/（由 electron-builder 生成）
• 默认打包目标：
  • macOS: dmg
  • Windows: nsis

如需自定义产品名、AppID、图标和目标平台，请在 package.json 的 build 字段中调整。

运行时行为说明

路由与页面

• 使用 Hash 路由（createWebHashHistory），兼容 file:// 协议。
• 入口 /#/login 为登录窗口；登录成功后通过 IPC 通知主进程打开主窗口。
• 示例子页：/home（报告生成占位）、/tem（模板管理占位）。

窗口与 IPC

• 预加载脚本在 window.electronAPI 暴露方法（electron/preload.ts）：
  • openMainWindow()：从登录切换到主窗口
  • logoutToLoginWindow()：从主窗口退出并回到登录
  • db.insertSystemSetting(templateBaseUrl, reportSave) → Promise<number>
  • db.getSystemSetting() → Promise<{ id; templateBaseUrl; reportSave; status; createdAt } | null>
  • db.updateSystemSetting(id, data) → Promise<void>
  • db.insertTemplate(fileUrl) / db.deleteTemplate(id) / db.listTemplates()

渲染层示例：

// 登录后切换窗口
if ((window as any)?.electronAPI?.openMainWindow) {
  (window as any).electronAPI.openMainWindow()
}

// 读取系统设置
const setting = await window.electronAPI.db.getSystemSetting()

提示：src/types/preload.d.ts 中的类型仅为示例，若需完善类型提示，可按实际 API 同步维护。

本地数据库（SQLite）

• 数据文件路径：app.getPath('userData')/app.db
• 首次启动会：
  • 自动创建表：system_setting、report_template、report_result_template
  • 插入一条启用的 system_setting 默认记录，并在 userData 目录下创建：
    • TemplateBaseUrl/
    • ReportSaveUrl/
• 通过 electron/repository.ts 暴露 CRUD 能力，并在 main.ts 注册 IPC handler。

状态管理与主题

• 全局状态位于 src/stores/global-store.ts，持久化到 localStorage：
  • 主题明暗（自动跟随/手动切换）
  • 头部与面包屑显示
  • 侧边栏收起状态（可按需开启持久化）
  • “小知AI/控制台” 切换示例

常用脚本

• npm run dev：启动开发（Vite + Electron）
• npm run build：类型检查、前端构建、Electron 打包
• npm run rebuild：重建原生依赖（better-sqlite3）
• npm run drizzle:generate：基于 electron/schema.ts 生成迁移
• npm run drizzle:migrate：执行迁移（可用于非运行时的结构演进）

DevTools 提示（Autofill 报错）

• 含义：开发时打开 DevTools，前端会尝试调用 Autofill.enable / Autofill.setAddresses。当前捆绑的 Chromium 后端未暴露该域，控制台会出现：
  • Request Autofill.enable failed. 'Autofill.enable' wasn't found
  • Request Autofill.setAddresses failed. 'Autofill.setAddresses' wasn't found
• 影响：无功能影响，可忽略。
• 处理：默认不自动打开 DevTools；如需调试，可按需打开（见上文“开发调试”）。
• 可选：升级 Electron 版本至与 DevTools 前端匹配的版本；或清理/调整 DevTools 实验特性设置。

疑难排查

• better-sqlite3 报错（ABI/平台不匹配）：
  • npm run rebuild 重建原生依赖。
  • 确保本机构建工具链可用（见“环境要求”）。
• Electron 窗口无页面/白屏：
  • 确认 VITE_DEV_SERVER_URL 是否设置（开发模式）或 dist/index.html 是否生成（生产）。
  • Hash 路由路径是否正确（/#/login、/#/home 等）。
• 预加载类型不匹配：
  • 同步维护 src/types/preload.d.ts 与 electron/preload.ts 的实际 API。

许可

MIT