添加 Electron 和 electron-builder 到现有 Vite 项目

1. 安装

Electron 安装时，会访问 Github 下载对应的 Electron 包，但是由于一些众所周知的原因，国内访问 Github 会比较困难，故需要配置代理访问或使用国内镜像源

1.1 配置代理

• 当前方法为配置代理并直接访问 Github ，故和1.2 使用国内镜像源二选一即可

$env:ELECTRON_GET_USE_PROXY=1
$env:GLOBAL_AGENT_HTTP_PROXY=http://username:password@server:port
$env:GLOBAL_AGENT_HTTPS_PROXY=http://username:password@server:port

http://username:password@server:port应当被替换为你的代理地址，如： http://127.0.0.1:8081

Electron 代理设置：electron-proxy-doc

注：$env:是Windows Powershell中设置环境变量的方法，该环境变量仅适用于当前terminal，建议将相关配置置入.npmrc中，在项目根目录下建立.npmrc文件并填入以下内容即可

ELECTRON_GET_USE_PROXY=1
GLOBAL_AGENT_HTTP_PROXY=http://username:password@server:port
GLOBAL_AGENT_HTTPS_PROXY=http://username:password@server:port

填入.npmrc后可以使用npm config ls命令检查配置信息

1.2 使用国内镜像源

• 当前方法为配置国内镜像源以替代访问 Github，故和1.1 配置代理二选一即可

$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
$env:ELECTRON_CUSTOM_DIR="{{ version }}"

Electron 国内镜像设置：electron-custom-mirror

1.3 安装 Electron 和 electron-builder

npm install --verbose electron electron-builder --save-dev

1.4 安装 vite-plugin-electron 和 vite-plugin-electron-renderer

npm install vite-plugin-electron vite-plugin-electron-renderer --save-dev

2. 创建 electron/index.js

在项目根目录建立electron文件夹，在文件夹内创建index.js并填入以下内容

import { app, BrowserWindow } from 'electron';

function createWindow() {
    const browser = new BrowserWindow({
        width: 800,
        height: 650,
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true,
        }
    })
    // 在调用`vite`命令启动Vite时, 可以使用环境变量`process.env.VITE_DEV_SERVER_URL`
    if (process.env.VITE_DEV_SERVER_URL) {
        console.log('vite dev server url:', process.env.VITE_DEV_SERVER_URL)
        browser.loadURL(process.env.VITE_DEV_SERVER_URL)
        browser.webContents.openDevTools({mode:'right'})
    } else {
        // 加载文件，`dist/index.html`是Vite构建的默认输出目录
        browser.loadFile('dist/index.html');
    }
}

app.whenReady().then(() => {
    createWindow();

    app.on('activate', () => {
        // 应用启动后无窗口则重新创建窗口
        if (BrowserWindow.getAllWindows().length === 0) createWindow()
    });

    app.on('window-all-closed', () => {
        // 关闭窗口后终止应用
        if (process.platform !== 'darwin') app.quit()
    });
});

这将会在编译后的 Electron 应用启动时, 区分dev环境并创建对应窗口

详见：Electron官方文档-将网页装载到BrowserWindow

注：Electron 版本低于28的情况下不支持ESM规范，请使用require导入

const { app, BrowserWindow } = require('electron/main')

3. 配置 vite.config.js

因为使用了vite-plugin-electron来集成 Electron 和 Vite, 故需要添加以下字段到vite.config.js的plugins部分

import electron from 'vite-plugin-electron/simple'

export default defineConfig({
  plugins: [
    electron({
      main: {
        // Shortcut of `build.lib.entry`
        entry: 'electron/index.js',
      },
      // preload: {
      //   // Shortcut of `build.rollupOptions.input`
      //   input: 'electron/preload.ts',
      // },
      // Optional: Use Node.js API in the Renderer process
      renderer: {},
    }),
})

preload 字段为加载应用预加载脚本，详见：Electron官方文档-使用预加载脚本

4. 配置 package.json

4.1 配置 Electron

除了 package.json 文件包含的必要字段之外，为使用 Electron，package.json 文件还必须包含main字段，以定义 Electron 应用的入口

{
    "main": "dist-electron/index.js",
}

• main：Electron应用的入口文件位置

  此处指向了dist-electron/index.js，这是因为使用了vite-plugin-electron来集成 Electron 和 Vite，在执行vite build命令后，electron/index.js默认会被编译到dist-electron/index.js

4.2 配置 electron-builder

4.2.1 name & description & version

electron-builder 需要额外的name、description和version字段来为应用提供描述信息

{
    "name": "your-app-name",
    "description": "Your App description",
    "version": "0.0.0.0"
}

• name：应用的名称，应当使用没有空格的唯一名称，以避免与其他应用程序冲突
• description：应用的描述，用以简短的说明该应用的功能
• version：应用的版本

4.2.2 build

build字段是 electron-builder 配置的核心，该字段被用来自定义构建过程和结果，例如：包名、图标、输出平台设置等，这是一个基本的build字段示例：

{
    "build": {
        "productName": "YourApp",
        "appId": "com.yourwebsite.yourapp",
        "directories": {
            "output": "build"
        },
        "win": {
            "icon": "public/icon.png",
            "target": ["portable"],
            "artifactName": "${productName}_${version}.${ext}"
        },
        "compression": "maximum",
        "files": [
            "dist/**/*"
        ]
    },
}

• productName：指定了构建的应用的名称，该名称将用于安装过程中和生成的安装文件

• appId：应用的唯一标识符

• directories：

  • output：electron-builder 输出构建文件的目录
  • win：Windows 平台的构建选项
    • icon：应用的图标
    • target：构建目标，此处使用portable来构建一个免安装的单文件应用
    • artifactName：构建结果的命名方式，使用模板字符串配置，详参：文件名模板字符串选项

• compression：构建过程中使用的压缩级别，此处采用最高压缩以减小编译后应用大小

• files：文件包含/排除设置，此处设置以包含dist目录下所有文件

此处仅提供了基本的配置示例，其余参数详参：electron-builder 通用配置

4.3 启动和编译脚本

{
    "script": {
        "electron:start": "electron --trace-warnings .",
    	"electron:build": "vite build && electron-builder",
    	"electron:postinstall": "electron-builder install-app-deps"
    }
}

• electron:start：默认的 Electron 启动脚本（可省略），因已经配置了vite.config.js，故调用vite命令时将自动启动Electron
• electron:build：顺序调用vite build和electron-builder来一键完成 Vite 构建和 electron-builder 构建
• electron:postinstall：安装 electron-builder 依赖项

ESM Module

Electron 最近正式兼容了 ESM 规范，在项目中启用需要满足以下条件：

• 项目package.json中包含顶置的"type": "module"字段
• Electron 版本大于等于28.0.0
• vite-plugin-electron 版本大于等于0.28.0-beta.1

{
  "type": "module",
  "devDependencies": {
    "electron": "^28.0.0",
    "vite-plugin-electron": "^0.28.0-beta.1",
  }
}