基于React+Vite+Electron搭建桌面程序项目实践

December 22, 2023 5715

项目背景

项目需要开发桌面程序，考虑到项目的跨平台性和需求迭代速度，使用Electron作为桌面程序的开发框架，使用React作为前端框架，使用Vite作为前端构建工具，这里记录一下项目的搭建过程。

项目介绍

1. 技术栈

  • node 20.10.0
  • react 18.2.0
  • vite 5.0.8
  • electron 28.1.0

2. 目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
├── README.md
├── electron-builder.json           # electron打包配置
├── electron-main.js                # electron入口文件
├── electron-preload.js             # electron预加载文件
├── index.html                      # vite打包模版文件
├── package.json                    # 项目依赖
├── public
│   └── vite.svg
├── src
│   ├── App.css                     # 应用样式
│   ├── App.tsx                     # 应用文件
│   ├── assets                      # 静态资源
│   ├── index.css                   # 全局样式
│   ├── main.tsx                    # vite入口文件
│   └── vite-env.d.ts               # vite环境变量
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
└── yarn.lock

项目搭建

1. 创建项目

1
2
3
4
5
6
7
8
# 使用yarn创建项目
yarn create vite mos
# 打开项目
cd mos
# 安装依赖
yarn
# 启动项目
yarn dev

使用yarn创建项目

2. 安装electron相关依赖

1
2
3
4
5
6
7
8
# 安装electron
yarn add -D electron
# 安装electron-builder，用于构建打包可安装程序
yarn add -D electron-builder
# 安装electron-devtools-installer，用于开发调试electron项目
yarn add -D electron-devtools-installer
# 安装electron和vite的桥接插件vite-plugin-electron，用于在渲染进程中使用框架功能
yarn add -D vite-plugin-electron

3. 配置electron

3.1 编写electron预加载文件

在项目根目录下创建electron预加载文件electron-preload.mjs，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/**
 * The preload script runs before. It has access to web APIs
 * as well as Electron's renderer process modules and some
 * polyfilled Node.js functions.
 *
 * https://www.electronjs.org/docs/latest/tutorial/sandbox
 */
import process from 'process'

window.addEventListener('DOMContentLoaded', () => {
    const replaceText = (selector, text) => {
      const element = document.getElementById(selector)
      if (element) element.innerText = text
    }
  
    for (const type of ['chrome', 'node', 'electron']) {
      replaceText(`${type}-version`, process.versions[type])
    }
  }
);

3.2 编写electron入口文件

在项目根目录下创建electron入口文件electron-main.js，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import path from 'path'
import process from 'process'

import { app, BrowserWindow } from 'electron'
import { join } from 'node:path'

// 关闭安全警告
// process.env['ELECTRON_DISABLE_SECURITY_WARNINGS'] = 'true';

const __dirname = path.resolve();

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      sandbox: false,
      preload: process.env.VITE_ELECTRON_PRELOAD_PATH ? join(__dirname, process.env.VITE_ELECTRON_PRELOAD_PATH) : 'electron-preload.mjs'
    }
  })

  // development模式
  if(process.env.VITE_DEV_SERVER_URL) {
      win.loadURL(process.env.VITE_DEV_SERVER_URL)
      // 开启调试台
      win.webContents.openDevTools()
  }else {
      win.loadFile('dist/index.html')
      // 开启调试台
      // win.webContents.openDevTools()
  }
}

app.whenReady().then(() => {
  createWindow()
  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

3.3 配置electron入口文件

修改package.json文件，添加electron入口文件配置：

1
2
3
4
5
{
  ...
  "main": "electron-main.js",
  ...
}

3.4 配置electron打包文件

在项目根目录下创建electron配置文件electron-builder.json，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
    "appId": "com.example.mos",
    "productName": "mos",
    "directories": {
        "output": "build"
    },
    "files": [
        "dist/",
        "electron-main.js",
        "electron-preload.mjs"
    ],
    "mac": {
        "target": "dmg",
        "category": "public.app-category.developer-tools"
    },
    "dmg": {
      "contents": [
        {
            "x": 130,
            "y": 220
        },
        {
            "x": 410,
            "y": 220,
            "type": "link",
            "path": "/Applications"
        }
      ]
    },
    "win": {
        "target": "nsis"
    },
    "nsis": {
        "oneClick": false,
        "perMachine": true,
        "allowToChangeInstallationDirectory": true
    }
}

修改package.json文件，添加electron打包脚本配置：

1
2
3
4
5
6
7
8
{
  ...
  "scripts": {
    ...
    "pack": "yarn run build && electron-builder --config=./electron-builder.json"
  },
  ...
}

4. 配置vite

4.1 配置vite环境变量

在项目根目录下创建.env.development文件，内容如下：

1
VITE_ELECTRON_PRELOAD_PATH=electron-preload.mjs

4.2 修改vite.config.ts文件

修改vite.config.ts文件，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react-swc'
import electron from 'vite-plugin-electron'

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  const viteEnv = loadEnv(mode, process.cwd())
  process.env = { ...process.env, ...viteEnv }

  return {
      plugins: [
          react(),
          electron({
              entry: 'electron-main.js',
          })
      ]
  }
})

项目运行

1. 开发启动

1
yarn dev

启动效果

2. 打包可执行程序

1
yarn pack

打包效果