使用 Electron 配置 React

使用 Electron 设置 React 项目时，先创建 Vite React 项目，然后将 electron 和 electron-builder 添加为 devDependencies。最终，项目会有两个入口点：用于渲染进程的 Vite 应用，以及用于 Electron 主进程的 main.js 文件。

main.js 是 Electron 的入口点。它会按照您所需的窗口尺寸和安全设置创建 BrowserWindow，然后加载 React 应用——开发期间指向 localhost:5173，生产环境则指向构建后的文件路径。

electron-vite 是一个一体化构建工具，可将 Vite 与 Electron 集成，并自动处理复杂的多进程构建配置。它会为主进程、预加载脚本和渲染进程分别提供 Vite 配置，并显著简化开发和生产构建。

为 Electron 配置 Vite 时，必须明确设置浏览器目标，而不能依赖自动检测，因为渲染进程运行在 Electron 捆绑的特定 Chromium 版本中。electron-vite 会自动处理这一点，但手动设置时，必须在构建目标中指定 chrome 版本。

运行 electron-vite dev 会同时启动用于渲染进程的 Vite 开发服务器和 Electron 主进程。Vite 开发服务器提供热模块替换，因此 React 组件的更改会立即显示在 Electron 窗口中，无需完全重启。

HMR 在 Electron 渲染进程中的工作方式与浏览器中一样——编辑后的组件会立即重新渲染，同时保留状态。只有修改 main.js 或预加载脚本才需要完全重启 Electron，因为它们运行在 Vite HMR 边界之外。

Electron + React + TypeScript 项目需要为主进程（目标为 Node.js/CommonJS）、预加载脚本（目标为带有 Node 全局变量的类浏览器环境）和渲染进程（标准浏览器 TypeScript）分别设置 tsconfig 文件。electron-vite 会自动生成这些配置。

预加载脚本使用 contextBridge.exposeInMainWorld 向渲染进程暴露自定义 API。典型做法是暴露一个名为“api”的命名空间，其中的函数封装 ipcRenderer.invoke 调用，为 React 组件提供简洁的异步接口，以执行主进程操作。

在任何 React 组件中，您都可以调用 window.api.myFunction() 来调用已暴露的预加载 API。TypeScript 用户通常会添加全局声明（window: Window & { api: MyAPI }），从而获得对已暴露接口的类型检查和自动补全。

electron-vite build 会将三个目标（主进程、预加载脚本、渲染进程）编译到 dist/ 文件夹中。然后，electron-builder 会将其打包为特定平台的安装程序。生产环境的 main.js 会从捆绑后的文件路径加载渲染进程，而不是从开发服务器 URL 加载。

最常见的设置错误包括：忘记将 nodeIntegration:false 和 contextIsolation:true（这会造成安全漏洞）、在 main.js 中加载错误的 URL（开发环境与生产环境混淆），以及直接在渲染进程中导入 Electron 模块（会导致崩溃）。electron-vite 的默认设置可以避免其中大多数问题。

运行 electron-vite dev 会实现什么？

electron-vite 通过处理多进程构建的复杂性，简化了 React 与 Electron 的设置过程。开发工作流提供完整的 HMR 支持，contextBridge 保护渲染进程 API 的暴露面，而独立的 TypeScript 配置则确保每个进程拥有正确的类型环境。生产构建使用 electron-builder 进行特定平台的打包。