English | 简体中文
一个现代化的 Electron + React 桌面应用开发模板，集成了丰富的功能和最佳实践。
- Electron: v37+ 跨平台桌面应用框架
- React: v19+ 用户界面库
- TypeScript: v5+ 类型安全的JavaScript超集
- Vite + electron-vite: 现代化构建工具
- Ant Design: 企业级UI组件库
- UnoCSS: 原子化CSS引擎
- Three.js + React Three Fiber: 3D图形渲染
- Zustand: 轻量级状态管理
- SWR: React Hooks数据获取库
- React Router: 客户端路由
- ESLint + Prettier: 代码规范和格式化
- electron-builder: 应用打包和分发
- 主进程与渲染进程间安全通信
- HTTP客户端封装(类似Axios)
- 系统信息获取(CPU、内存、网络等)
- 文件操作和对话框
- 响应式布局
- 暗黑模式支持
- 动画效果
- 毛玻璃效果
- Three.js集成
- GLB模型支持
- HDR环境贴图
- KTX2压缩纹理
- 增量更新支持
- GitHub Releases自动发布
- CI/CD自动构建流水线
- Windows (x64/arm64)
- macOS (x64/arm64)
- Linux (AppImage/Snap/Deb)
src/
├── main/ # 主进程代码
│ ├── index.ts # 主进程入口
│ ├── window-manager.ts # 窗口管理
│ ├── ipc-handles.ts # IPC处理器
│ └── auto-updater.ts # 自动更新
├── preload/ # 预加载脚本
│ └── index.ts # 预加载入口
└── renderer/ # 渲染进程代码
├── src/
│ ├── components/ # 可复用组件
│ ├── pages/ # 页面组件
│ ├── hooks/ # 自定义Hooks
│ ├── stores/ # 状态管理
│ ├── lib/ # 工具库
│ ├── router/ # 路由配置
│ ├── layout/ # 布局组件
│ ├── examples/ # 示例代码
│ ├── config/ # 配置文件
│ └── utils/ # 工具函数
└── index.html # HTML模板
$ pnpm install$ pnpm dev# 代码格式化
$ pnpm format
# 代码规范检查
$ pnpm lint
# TypeScript类型检查
$ pnpm typecheck# Windows平台
$ pnpm build:win
# macOS平台
$ pnpm build:mac
# Linux平台
$ pnpm build:linux
# 所有平台
$ pnpm build:all构建完成后，dist 目录会包含大量中间文件。项目提供了自动清理功能：
# 手动清理dist目录
$ pnpm clean:dist自动清理：所有构建命令（build:win、build:mac、build:linux、build:all）都会在构建完成后自动执行清理，只保留：
- 最终安装包文件（
.exe、.dmg、.deb、.snap、.AppImage） - Blockmap文件（用于增量更新）
- 自动更新配置文件（
.yml）
清理后可减少80%以上的磁盘占用。详细说明请参考：scripts/README.md
// 调用主进程方法
const systemInfo = await window.ipcRenderer.invoke('system-info')// 使用封装的HTTP客户端
import { useIpcAjax } from '@renderer/lib/ipc-ajax'
const { get, post } = useIpcAjax({ showLoading: true })
// GET请求
const data = await get('/api/users')
// POST请求
const result = await post('/api/users', { name: 'John' })// 使用Zustand管理状态
import { useCountStore } from '@renderer/stores/useCountStore'
const { count, inc, cut } = useCountStore()import { useNavigate } from 'react-router-dom'
const navigate = useNavigate()
navigate('/settings')应用的构建配置位于 electron-builder.yml 文件中，可以根据需要修改：
- 应用名称和图标
- 打包格式和目标平台
- GitHub仓库信息
- 安装程序选项
项目配置了 GitHub Actions 自动化工作流，支持自动构建和发布：
- 更新仓库信息：修改
electron-builder.yml中的 GitHub 仓库配置
publish:
provider: github
owner: your-github-username
repo: your-repo-name- 创建发布版本：
# 更新版本号并推送标签
npm version patch
git push origin --tags- 自动构建：GitHub Actions 会自动构建所有平台的安装包并发布到 Releases
GitHub Actions 工作流已集成自动清理功能：
- 自动执行：构建完成后自动清理
dist目录 - 节省空间：减少 80% 以上的存储使用
- 保留必要文件：只保留安装包、更新配置和校验文件
- 总是执行：无论构建成功或失败都会执行清理
详细配置请参考：GitHub Actions 工作流说明
- 标签触发：推送
v*.*.*格式的标签自动触发 - 本地发布：使用
pnpm release命令本地构建并发布
详细说明请参考：自动发布指南 | Auto Release Guide
项目集成了 electron-updater 用于自动更新：
- 应用启动时自动检查 GitHub Releases 中的最新版本
- 发现新版本时提示用户更新
- 支持增量更新和后台下载
- 主进程负责：窗口管理、系统API调用、文件操作、自动更新
- 渲染进程负责：UI渲染、用户交互、状态管理
- 通过IPC进行安全通信
- 将UI拆分为可复用的组件
- 使用自定义Hooks封装逻辑
- 保持组件的单一职责
- 使用TypeScript定义接口和类型
- 为IPC通信定义类型
- 避免使用
any类型
- English Documentation - Complete English documentation
- 自动发布指南 - 自动构建和发布流程说明
- Auto Release Guide - Automated build and release process guide (English)
- GitHub Actions 工作流说明 - 工作流配置和使用指南
- GitHub Actions Workflow Documentation - Workflow configuration and usage guide (English)
- GitHub Actions 权限配置 - 权限配置详细说明
- GitHub Actions Permissions Configuration - Permissions configuration guide (English)
- GitHub Actions 最佳实践指南 - 工作流最佳实践和优化建议
- GitHub Actions Best Practices Guide - Workflow best practices and optimization guide (English)
- GitHub Actions 故障排除指南 - 常见问题和解决方案
- GitHub Actions Troubleshooting Guide - Common issues and solutions (English)
- Scripts 工具说明 - 项目辅助脚本使用指南
- Scripts Tools Documentation - Project auxiliary scripts usage guide (English)
- 构建产物清理示例 - 清理脚本的详细使用示例
- Dist Directory Cleanup Example - Detailed usage examples of cleanup scripts (English)