# Electron_vue3 **Repository Path**: NativeBase/electron_vue3 ## Basic Information - **Project Name**: Electron_vue3 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-08-19 - **Last Updated**: 2025-08-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 🚀 Vite + Electron + Vue3 桌面应用开发模板
Vue 3 Electron Vite TypeScript Tailwind CSS

🍀 现代化的跨平台桌面应用开发解决方案

基于最新技术栈构建的 Electron + Vue3 开发模板，提供完整的开发、构建、打包工作流

## ✨ 特性 - 🎯 **现代化技术栈** - Vue 3 + TypeScript + Vite + Electron - ⚡ **极速开发体验** - Vite 热重载 + TypeScript 类型提示 - 🎨 **优雅的UI框架** - Tailwind CSS 原子化样式 - 🔧 **完整的工具链** - ESLint + Prettier + electron-builder - 📦 **跨平台打包** - 支持 Windows、macOS 应用打包 - 🛡️ **安全的IPC通信** - contextBridge + preload 安全机制 - 🎪 **系统集成** - 系统托盘、原生通知、窗口管理 - 📱 **响应式设计** - 适配不同屏幕尺寸 ## 🏗️ 技术架构 ``` ┌─────────────────┐ ┌─────────────────┐ │ 渲染进程 │ │ 主进程 │ │ │ │ │ │ Vue 3 + TS │◄──►│ Electron Main │ │ Tailwind CSS │ │ System APIs │ │ Vite HMR │ │ Window Mgmt │ └─────────────────┘ └─────────────────┘ ▲ ▲ │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Preload Script │ │ System Tray │ │ IPC Bridge │ │ Notifications │ │ Context Bridge │ │ File System │ └─────────────────┘ └─────────────────┘ ``` ## 📋 环境要求 - **Node.js**: >= 18.0.0 - **npm/pnpm**: 最新版本 - **操作系统**: Windows 10+, macOS 10.15+, Linux ## 🚀 快速开始 ### 1. 克隆项目 ```bash git clone cd vite-electron-vue3-template ``` ### 2. 安装依赖 ```bash # 使用 npm npm install # 或使用 pnpm (推荐) pnpm install ``` ### 3. 启动开发服务器 ```bash npm run dev ``` ### 4. 构建生产版本 ```bash # 构建前端资源 npm run build # 打包 Windows 应用 npm run win64 # 打包 macOS 应用 npm run mac ``` ## 📁 项目结构 ``` vite-electron-vue3-template/ ├── src/ # Vue3 前端源码 │ ├── App.vue # 主应用组件 │ ├── main.ts # Vue应用入口 │ ├── styles/ # 样式文件 │ └── assets/ # 静态资源 ├── src-electron/ # Electron 主进程源码 │ ├── main.ts # Electron主进程入口 │ ├── tray.ts # 系统托盘功能 │ └── utils.ts # 工具函数 ├── public/ # 静态资源 │ ├── favicon.ico # 应用图标 (Windows/Linux) │ ├── favicon.png # 应用图标 (macOS 系统托盘) │ └── preload.mjs # 预加载脚本 ├── app/ # Electron编译输出 ├── dist/ # 前端构建输出 ├── build/ # 应用打包输出 ├── docs/ # 项目文档 ├── vite.config.ts # Vite配置 ├── electron-builder.yml # 打包配置 └── package.json # 项目配置 ``` ## 🎨 图标配置 ### 图标文件要求 本项目支持多平台图标格式，确保在不同操作系统上的最佳显示效果： | 平台 | 格式 | 文件名 | 用途 | 建议尺寸 | |------|------|--------|------|----------| | **Windows/Linux** | ICO | `favicon.ico` | 窗口图标、系统托盘 | 256x256 | | **macOS** | PNG | `favicon.png` | 系统托盘 | 16x16, 32x32 | | **通用** | ICO | `favicon.ico` | 窗口图标、通知 | 256x256 | ### 图标放置位置 ``` public/ ├── favicon.ico # 主图标文件 (必需) └── favicon.png # macOS 系统托盘图标 (推荐) ``` ### 自动图标格式选择 应用会根据运行平台自动选择合适的图标格式： ```typescript // 系统托盘图标选择逻辑 const iconExtension = process.platform === 'darwin' ? 'png' : 'ico' const iconPath = `public/favicon.${iconExtension}` ``` **平台特性**: - **macOS**: 自动使用 PNG 格式，提供更好的系统托盘显示效果 - **Windows/Linux**: 使用 ICO 格式，保持传统兼容性 ### 图标生成工具 如果你只有一种格式的图标，可以使用以下命令转换： ```bash # 将 ICO 转换为 PNG (macOS) sips -s format png public/favicon.ico --out public/favicon.png # 将 PNG 转换为 ICO (需要 ImageMagick) convert public/favicon.png public/favicon.ico ``` ## 🛠️ 开发指南 ### 核心概念 #### 1. 双进程架构 - **主进程**: 管理应用生命周期、创建窗口、处理系统事件 - **渲染进程**: 运行 Vue3 应用，处理用户界面 #### 2. IPC 通信 ```typescript // 渲染进程发送消息 window.electronAPI.send('hello', '消息内容') // 主进程监听消息 ipcMain.on('hello', (event, args) => { console.log('收到消息:', args) }) ``` #### 3. 系统集成 - 系统托盘图标和右键菜单 - 原生系统通知 - 窗口状态管理 ### 开发工作流 1. **前端开发**: 在 `src/` 目录下开发 Vue3 组件 2. **主进程开发**: 在 `src-electron/` 目录下开发 Electron 功能 3. **样式开发**: 使用 Tailwind CSS 进行样式设计 4. **调试测试**: 使用开发者工具进行调试 5. **构建打包**: 使用 electron-builder 打包应用 ## 📦 构建与部署 ### 开发环境 ```bash npm run dev # 启动开发服务器 ``` ### 生产构建 ```bash npm run build # 构建前端资源 npm run lint # 代码检查 ``` ### 应用打包 ```bash npm run win64 # Windows 64位 npm run win32 # Windows 32位 npm run mac # macOS ``` ### 打包配置 打包配置位于 `electron-builder.yml`，支持自定义： - 应用图标和名称 - 安装包类型 - 代码签名 - 自动更新 ## 🔧 配置说明 ### Vite 配置 - **开发服务器**: localhost:3000 - **构建优化**: 代码分割、压缩、Tree Shaking - **TypeScript**: 完整类型检查支持 ### Electron 配置 - **安全设置**: 禁用 node 集成，启用上下文隔离 - **预加载脚本**: 安全的 IPC 通信桥梁 - **窗口设置**: 自定义窗口大小、图标、菜单 ### Tailwind CSS - **原子化样式**: 快速构建现代化界面 - **响应式设计**: 支持多种屏幕尺寸 - **自定义主题**: 可扩展的设计系统 ## 🤝 贡献指南 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 打开 Pull Request ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 ## 🙏 致谢 - [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架 - [Electron](https://electronjs.org/) - 跨平台桌面应用框架 - [Vite](https://vitejs.dev/) - 下一代前端构建工具 - [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架 ## 🔧 故障排除 ### 常见问题 #### 1. 图标加载失败 **问题**: 控制台显示 "Failed to load image from path" 错误 **解决方案**: ```bash # 检查图标文件是否存在 ls -la public/favicon.ico public/favicon.png # 如果缺少 PNG 格式图标，转换现有 ICO 文件 sips -s format png public/favicon.ico --out public/favicon.png # 重新构建应用 npm run build npm run dev ``` #### 2. 系统托盘不显示 (macOS) **问题**: macOS 系统托盘图标不显示或显示异常 **解决方案**: - 确保 `public/favicon.png` 文件存在 - 检查 PNG 文件格式是否正确 - 建议使用 16x16 或 32x32 像素的 PNG 图标 #### 3. 应用启动失败 **问题**: UnhandledPromiseRejectionWarning 错误 **解决方案**: ```bash # 清理构建缓存 rm -rf app/ dist/ node_modules/.vite # 重新安装依赖 npm install # 重新构建 npm run build ``` #### 4. 开发环境热重载问题 **问题**: 修改代码后应用不自动重启 **解决方案**: - 检查端口是否被占用 - 重启开发服务器 - 检查 Vite 配置是否正确 ### 调试技巧 #### 启用详细日志 在开发环境中，应用会输出详细的调试信息： ```bash # 启动开发模式查看日志 npm run dev # 查看图标加载状态 # 控制台会显示: # "系统托盘图标加载成功: /path/to/favicon.png" # "窗口图标加载成功: /path/to/favicon.ico" ``` #### 检查文件权限 ```bash # 确保图标文件有正确的读取权限 chmod 644 public/favicon.ico public/favicon.png ``` ### 获取帮助 如果遇到其他问题： 1. 查看 [项目文档](docs/) 获取详细信息 2. 搜索 [已知问题](../../issues) 3. 提交新的 [Issue](../../issues/new) 并提供： - 操作系统版本 - Node.js 版本 - 错误日志 - 复现步骤 ## 📞 支持 如果你觉得这个项目有帮助，请给它一个 ⭐️ 有问题或建议？欢迎提交 [Issue](../../issues) 或 [Pull Request](../../pulls) ---

用 ❤️ 构建 | Made with ❤️