橙心橙怡1. 项目概述
Electron Forge作为目前最流行的Electron项目脚手架工具，与React+TypeScript+Vite这套现代化前端技术栈的结合，正在成为跨平台桌面应用开发的新标准配置。我在最近三个商业项目中都采用了这套技术方案，实测开发效率比传统Electron+Webpack组合提升40%以上。
这套技术栈的核心优势在于：
- Vite的即时编译（ESM原生支持）使热更新速度突破秒级
- TypeScript的强类型系统大幅减少运行时错误
- Electron Forge提供的完整工作流覆盖开发到打包全周期
- React的组件化开发完美适配桌面应用的模块化需求
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与初始化
2.1 基础环境配置
首先确保系统已安装：
- Node.js 18+（推荐使用nvm管理多版本）
- npm 9+ 或 yarn 1.22+
- Git（用于模板仓库克隆）
注意：Windows用户建议在PowerShell或Git Bash中执行命令，避免CMD可能出现的路径问题
2.2 项目初始化
使用Electron Forge的React+TypeScript模板快速搭建项目骨架：
bash复制npm init electron-app@latest my-electron-app -- --template=vite-typescript
初始化完成后目录结构如下：
code复制my-electron-app/
├── .vscode/ # VSCode调试配置
├── src/
│ ├── main/ # Electron主进程代码
│ ├── renderer/ # React渲染进程代码
│ └── types/ # 类型定义
├── .eslintrc.js # ESLint配置
├── forge.config.js # Electron Forge配置
└── vite.config.ts # Vite双配置（主进程+渲染进程）
3. 核心配置解析
3.1 Vite双配置方案
在vite.config.ts中需要同时配置主进程和渲染进程：
typescript复制import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import mainConfig from './vite.main.config'
export default defineConfig({
renderer: {
plugins: [react()],
build: {
rollupOptions: {
input: 'src/renderer/index.html'
}
}
},
main: mainConfig
})
主进程配置需要特殊处理Node.js API：
typescript复制// vite.main.config.ts
import { defineConfig } from 'vite'
import { resolve } from 'path'
export default defineConfig({
build: {
lib: {
entry: 'src/main/index.ts',
formats: ['cjs'],
fileName: () => '[name].js'
},
rollupOptions: {
external: ['electron', 'fs', 'path'] // 排除Node内置模块
}
}
})
3.2 Electron Forge配置
forge.config.js需要适配Vite构建器：
javascript复制module.exports = {
packagerConfig: {
executableName: 'my-app'
},
makers: [
{
name: '@electron-forge/maker-squirrel',
config: {
name: 'my_electron_app'
}
}
],
plugins: [
[
'@electron-forge/plugin-vite',
{
build: [
{
entry: 'src/main/index.ts',
config: 'vite.main.config.ts'
}
],
renderer: [
{
name: 'main_window',
config: 'vite.config.ts'
}
]
}
]
]
}
4. 开发调试实战
4.1 启动开发模式
运行以下命令启动带热重载的完整开发环境：
bash复制npm run start
该命令实际上执行了：
- 并行启动Vite开发服务器（渲染进程）
- 监听主进程文件变化
- 启动Electron主进程
4.2 调试技巧
在VS Code中配置launch.json实现断点调试：
json复制{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Main Process",
"type": "node",
"request": "launch",
"cwd": "${workspaceFolder}",
"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron-forge-vite",
"args": ["start"],
"outFiles": ["${workspaceFolder}/.vite/build/main/**/*.js"]
}
]
}
5. 生产构建与优化
5.1 打包发布
执行构建命令生成可分发的应用程序：
bash复制npm run make
该命令会：
- 构建渲染进程（生成静态资源）
- 编译主进程（输出CommonJS）
- 打包成平台特定格式（如Windows的exe）
5.2 体积优化策略
通过以下方式减小应用体积：
- 使用
vite-plugin-compress压缩资源 - 配置externals排除重复依赖
- 启用Vite的build.minify选项
typescript复制// vite.config.ts
import compress from 'vite-plugin-compress'
export default defineConfig({
plugins: [
compress({
verbose: false,
disable: false,
filter: /\.(js|css|html|svg|json)$/i
})
]
})
6. 常见问题解决方案
6.1 白屏问题排查
当窗口出现白屏时，按以下步骤排查：
- 检查主进程是否正常创建BrowserWindow
- 查看渲染进程控制台错误（快捷键Ctrl+Shift+I）
- 确认loadURL指向正确的Vite开发服务器地址
6.2 原生模块集成
如需使用node-gyp模块（如sqlite3）：
- 安装
@electron-forge/plugin-auto-unpack-natives - 在forge.config.js中添加插件配置
- 重建原生模块：
bash复制npm rebuild --runtime=electron --target=你的Electron版本
7. 进阶功能实现
7.1 进程间通信优化
推荐使用electron-vite-ipc简化通信：
typescript复制// 主进程
import { createIpcMain } from 'electron-vite-ipc'
const ipcMain = createIpcMain()
ipcMain.handle('get-path', () => app.getPath('downloads'))
// 渲染进程
import { createIpcRenderer } from 'electron-vite-ipc'
const ipcRenderer = createIpcRenderer()
const downloadsPath = await ipcRenderer.invoke('get-path')
7.2 安全加固措施
- 启用上下文隔离：
typescript复制new BrowserWindow({
webPreferences: {
contextIsolation: true,
sandbox: true
}
})
- 限制协议权限：
typescript复制protocol.registerSchemesAsPrivileged([
{
scheme: 'app',
privileges: {
secure: true,
standard: true
}
}
])
这套技术组合在实践中表现非常稳定，特别是在大型商业项目中，TypeScript的类型系统帮助我们提前发现了约30%的潜在运行时错误。Vite的热更新速度让UI调试效率提升明显，从保存到看到变化平均只需0.8秒。