3步打造跨平台桌面应用：Electron React Boilerplate实战指南

宗嫣惠

1024人浏览 · 2025-08-23 11:15:58

宗嫣惠 · 2025-08-23 11:15:58 发布

3步打造跨平台桌面应用：Electron React Boilerplate实战指南

【免费下载链接】electron-react-boilerplate 项目地址: https://gitcode.com/gh_mirrors/el/electron-react-boilerplate

你还在为桌面应用开发的复杂配置烦恼吗？还在纠结如何将React前端与原生功能完美结合？本文将带你使用Electron React Boilerplate（ERB）快速构建专业级桌面应用，从环境搭建到打包发布，全程仅需3个步骤，即使是开发新手也能轻松上手。读完本文，你将掌握跨平台应用开发的核心流程，解决常见的配置难题，并能独立完成应用的构建与分发。

项目概述：为什么选择Electron React Boilerplate？

Electron React Boilerplate（简称ERB）是一个集成了Electron、React、React Router和Webpack的开箱即用开发框架。它解决了桌面应用开发中的三大痛点：繁琐的环境配置、前端与原生功能的通信障碍、跨平台打包复杂性。通过预置的最佳实践和优化配置，ERB让开发者能够专注于业务逻辑而非工具链配置。

项目核心架构采用分层设计：

主进程（Main Process）：负责窗口管理、原生API调用等系统级功能，代码位于src/main/目录
渲染进程（Renderer Process）：基于React的前端界面，代码位于src/renderer/目录
预加载脚本（Preload Script）：安全地在主进程与渲染进程间建立通信桥梁，实现于src/main/preload.ts

ERB的优势在于其高度优化的开发体验，包括热重载、代码分割、自动更新等特性，这些都通过精心设计的配置文件实现，如package.json和tsconfig.json。

步骤一：环境搭建与项目初始化

1.1 安装前提条件

在开始前，请确保你的开发环境已安装：

Node.js（建议v14+）
npm（通常随Node.js一起安装）
Git

1.2 获取项目代码

通过Git克隆仓库到本地：

git clone --depth 1 --branch main https://gitcode.com/gh_mirrors/el/electron-react-boilerplate.git my-electron-app
cd my-electron-app

1.3 安装依赖

使用npm安装项目所需的所有依赖：

npm install

这一步会根据package.json中的配置，安装Electron、React、TypeScript等核心依赖。如果遇到安装问题，可以参考项目的调试指南或检查网络连接。

步骤二：开发与调试

2.1 启动开发服务器

运行以下命令启动开发环境：

npm start

该命令会同时启动两个进程：

React开发服务器（支持热重载）
Electron应用窗口（自动加载React页面）

开发模式下，ERB会使用.erb目录中的开发配置，包括Webpack配置和环境变量设置。你可以在src/main/main.ts文件中找到窗口创建的核心逻辑：

const createWindow = async () => {
  // 窗口配置与创建逻辑
  mainWindow = new BrowserWindow({
    show: false,
    width: 1024,
    height: 728,
    icon: getAssetPath('icon.png'),
    webPreferences: {
      preload: app.isPackaged
        ? path.join(__dirname, 'preload.js')
        : path.join(__dirname, '../../.erb/dll/preload.js'),
    },
  });
  
  mainWindow.loadURL(resolveHtmlPath('index.html'));
};

2.2 开发你的第一个功能

让我们修改React组件来定制应用界面。打开src/renderer/App.tsx，这是应用的根组件：

function Hello() {
  return (
    <div>
      <div className="Hello">
        <img width="200" alt="icon" src={icon} />
      </div>
      <h1>我的第一个Electron应用</h1> {/* 修改这里的标题 */}
      {/* 其他内容保持不变 */}
    </div>
  );
}

保存文件后，Electron窗口会自动刷新，你将看到修改后的标题。这个热重载功能极大提高了开发效率，无需手动重启应用。

2.3 主进程与渲染进程通信

ERB通过IPC（进程间通信）机制安全地实现主进程与渲染进程的通信。在src/main/preload.ts中定义通信接口，在渲染进程中通过window.electron.ipcRenderer调用。

示例：添加一个简单的IPC通信功能

在preload.ts中添加：

contextBridge.exposeInMainWorld('electron', {
  ipcRenderer: {
    myPing() {
      ipcRenderer.send('ipc-example', 'ping');
    },
    on(channel: string, func: (...args: unknown[]) => void) {
      const validChannels = ['ipc-example'];
      if (validChannels.includes(channel)) {
        ipcRenderer.on(channel, (event, ...args) => func(...args));
      }
    }
  }
});

在主进程src/main/main.ts中添加处理逻辑：

ipcMain.on('ipc-example', async (event, arg) => {
  const msgTemplate = (pingPong: string) => `IPC test: ${pingPong}`;
  console.log(msgTemplate(arg));
  event.reply('ipc-example', msgTemplate('pong'));
});

在渲染进程中使用：

// 在App.tsx中添加
useEffect(() => {
  window.electron.ipcRenderer.on('ipc-example', (arg) => {
    console.log(arg); // 打印 "IPC test: pong"
  });
  window.electron.ipcRenderer.myPing();
}, []);

步骤三：应用打包与分发

3.1 打包本地应用

当开发完成后，使用以下命令为当前平台打包应用：

npm run package

打包过程由electron-builder处理，配置文件为package.json中的"build"字段。打包完成的应用会生成在release/目录下。

打包过程会自动处理：

代码压缩与优化
资源文件整合
平台特定的可执行文件生成
应用元数据配置（名称、图标等）

3.2 自定义打包配置

你可以通过修改package.json来自定义打包行为，例如更改应用名称、版本号或添加平台特定设置：

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "build": {
    "appId": "com.mycompany.myapp",
    "productName": "我的应用",
    "icon": "assets/icon.icns",
    "mac": {
      "category": "public.app-category.utilities"
    },
    "win": {
      "target": "nsis"
    }
  }
}

3.3 跨平台打包

要为其他平台打包（需在对应平台环境下）：

Windows: npm run package:win
macOS: npm run package:mac
Linux: npm run package:linux

打包结果将包含完整的安装程序或可执行文件，可直接分发给用户。

进阶技巧与最佳实践

4.1 项目结构最佳实践

随着应用规模增长，建议采用以下目录结构组织代码：

src/
├── main/              # 主进程代码
│   ├── api/           # 原生API封装
│   ├── handlers/      # IPC处理器
│   └── utils/         # 工具函数
├── renderer/          # 渲染进程代码
│   ├── components/    # React组件
│   ├── hooks/         # 自定义Hooks
│   ├── pages/         # 页面组件
│   └── utils/         # 前端工具函数
└── common/            # 共享类型和常量