ByteNoteByteNote
字

字节笔记本

2026年2月22日

electron-vite-react：Electron + Vite + React 桌面应用模板

#开源工具

本文介绍 electron-vite-react，一个基于 Electron + Vite + React + TypeScript 的桌面应用开发模板。该项目由 electron-vite 组织维护，在 GitHub 上已获得 2.4k stars，是构建现代跨平台桌面应用的优秀起点。

项目简介

electron-vite-react 是一个开箱即用的 Electron 应用模板，它整合了当下最流行的前端技术栈：

  • Electron - 跨平台桌面应用框架
  • Vite - 下一代前端构建工具
  • React - 用户界面库
  • TypeScript - 类型安全的 JavaScript 超集

该项目基于 Vite 官方 template-react-ts 模板构建，如果你熟悉 Vite 的 React 项目结构，上手这个模板将非常容易。

核心特性

  • 📦 开箱即用 - 零配置即可开始开发
  • 🎯 熟悉的项目结构 - 基于 Vite 官方 React TypeScript 模板
  • 🌱 易于扩展 - 灵活的架构设计，方便自定义
  • 💪 支持 Node.js API - 在渲染进程中直接使用 Node.js 能力
  • 🔩 支持 C/C++ 原生扩展 - 可集成原生模块
  • 🐞 内置调试配置 - 包含完整的调试器配置
  • 🖥 多窗口支持 - 轻松实现多窗口应用

技术栈

技术用途版本要求
Electron桌面应用框架最新版
Vite构建工具最新版
ReactUI 框架18+
TypeScript类型系统4.5+
Tailwind CSS原子化 CSS集成支持
PlaywrightE2E 测试集成支持
electron-builder应用打包集成支持

安装指南

前置要求

  • Node.js >= 14.18.0 || >= 16.0.0
  • npm / yarn / pnpm

快速开始

bash
# 克隆项目
git clone https://github.com/electron-vite/electron-vite-react.git

# 进入项目目录
cd electron-vite-react

# 安装依赖
npm install

# 启动开发服务器
npm run dev

可用命令

bash
# 开发模式
npm run dev

# 构建生产版本
npm run build

# 运行测试
npm run test

# 打包应用
npm run dist

项目结构

text
├── electron/                 # Electron 相关代码
│   ├── main/                # 主进程源码
│   └── preload/             # 预加载脚本源码
│
├── release/                 # 构建输出目录
│   └── {version}/
│       ├── {os}-{os_arch}/  # 未打包的应用程序
│       └── {app_name}_{version}.{ext}  # 安装包
│
├── public/                  # 静态资源
├── src/                     # 渲染进程源码 (React 应用)
├── build/                   # 构建配置
└── test/                    # 测试文件

项目结构清晰分离了 Electron 主进程代码和 React 渲染进程代码，开发体验与纯 Web 应用几乎一致。

使用示例

主进程与渲染进程通信

预加载脚本 (electron/preload/index.ts)

typescript
import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('electronAPI', {
  sendMessage: (channel: string, data: any) => {
    ipcRenderer.send(channel, data)
  },
  onMessage: (channel: string, callback: Function) => {
    ipcRenderer.on(channel, (_, data) => callback(data))
  }
})

渲染进程中使用

typescript
// 在 React 组件中使用
function App() {
  const handleClick = () => {
    window.electronAPI.sendMessage('ping', 'Hello from React!')
  }

  return <button onClick={handleClick}>Send Message</button>
}

使用 Node.js API

得益于 electron-vite 的配置，你可以直接在渲染进程中使用 Node.js API：

typescript
import { readFile } from 'fs/promises'

async function loadConfig() {
  const config = await readFile('./config.json', 'utf-8')
  return JSON.parse(config)
}

进阶功能

自动更新

项目集成了 electron-updater，支持应用自动更新功能。详细配置请参考项目中的 src/components/update/README.md。

E2E 测试

集成了 Playwright 进行端到端测试：

bash
# 运行 E2E 测试
npm run test:e2e

调试配置

项目内置了 VS Code 调试配置，支持：

  • 主进程调试
  • 渲染进程调试
  • 同时调试两者

常见问题

如何处理 C/C++ 原生模块？

参考 vite-plugin-electron-renderer 文档进行预构建配置。

dependencies vs devDependencies

  • dependencies - 需要在运行时使用的包（如 Electron 主进程依赖）
  • devDependencies - 仅开发时使用的包（如 React、Vite 等，会被打包到渲染进程）

详细说明请参考 官方文档。

相关资源

许可证

MIT License

如果你正在寻找一个现代化、易用且功能完善的 Electron 开发模板，electron-vite-react 是一个值得尝试的选择。它结合了 Vite 的快速构建能力和 React 的组件化开发体验，让桌面应用开发变得简单而高效。

开源工具
上一篇

electron-vite - Electron 的下一代构建工具

下一篇

electron-vite-react：Electron + Vite + React 桌面应用模板

分享: