electron-vite/README.zh-CN.md

electron-vite

English | 简体中文

新一代 Electron 开发构建工具

---

特性

• ⚡️使用方式与 Vite 相同
• 🔨主进程/渲染进程/ preload 脚本都使用 Vite 构建
• 📃统一所有配置，合并到一个文件中
• 📦预设构建配置，无需关注配置
• 🚀支持渲染进程热更新(HMR)

用法

安装

npm i electron-vite -D

开发 & 编译

在安装了 electron-vite 的项目中，可以直接使用 npx electron-vite 运行， 也可以在 package.json 文件中添加 npm scripts ：

{
  "scripts": {
    "start": "electron-vite preview", // 开启 Electron 预览生产构建
    "dev": "electron-vite dev", // 开启开发服务并启动 Electron 程序
    "prebuild": "electron-vite build" // 为生产打包构建
  }
}

为了使用热更新(HMR)，需要使用环境变量（ELECTRON_RENDERER_URL）来决定 Electron 窗口加载本地页面还是远程页面。

function createWindow() {
  // 创建窗口
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js')
    }
  })

  // 开发模式下使用支持HMR的远程地址，生产模式下使用本地html页面
  if (!app.isPackaged && process.env['ELECTRON_RENDERER_URL']) {
    mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])
  } else {
    mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'))
  }
}

注意：在开发中，渲染进程 index.html 文件需要通过 <script type="module"> 引用脚本。

推荐项目目录

├──src
│  ├──main
│  │  ├──index.js
│  │  └──...
│  ├──preload
│  │  ├──index.js
│  │  └──...
│  └──renderer
│     ├──src
│     ├──index.html
│     └──...
├──electron.vite.config.js
└──package.json

开始学习

克隆 electron-vite-boilerplate 模板或者使用 create-electron 脚手架来搭建项目学习。

npm init @quick-start/electron

配置

配置文件

当以命令行方式运行 electron-vite 时，将会自动尝试解析项目根目录中名为 electron.vite.config.js 的配置文件。最基本的配置文件如下所示：

// electron.vite.config.js
export default {
  main: {
    // vite 配置选项
  },
  preload: {
    // vite 配置选项
  },
  renderer: {
    // vite 配置选项
  }
}

你可以显式地通过 --config 命令行选项指定一个配置文件（相对于 cwd 路径进行解析）：

electron-vite --config my-config.js

提示：electron-vite 也支持 ts 或者 mjs 的配置文件。

配置智能提示

因为 electron-vite 本身附带 Typescript 类型，所以你可以通过 IDE 和 jsdoc 的配合来实现智能提示：

/**
 * @type {import('electron-vite').UserConfig}
 */
const config = {
  // ...
}

export default config

你还可以使用 defineConfig and defineViteConfig 工具函数，这样不用 jsdoc 注解也可以获取类型提示：

import { defineConfig, defineViteConfig } from 'electron-vite'

export default defineConfig({
  main: {
    // ...
  },
  preload: {
    // ...
  },
  renderer: defineViteConfig(({ command, mode }) => {
    // 条件配置可使用 defineViteConfig
    // ...
  })
})

提示：defineViteConfig 从 Vite 中导出。

配置参考

见 vitejs.dev

配置预设

主进程编译项预设：

• outDir：out\main（相对于根目录）
• target：node*，自动匹配 Electron 的 node 构建目标，如 Electron 17 为 node16.13
• lib.entry：src\main\{index|main}.{js|ts|mjs|cjs}（相对于根目录），找不到则为空
• lib.formats：cjs
• rollupOptions.external：electron 和所有内置 node 模块(如果用户配置了外部模块ID，将自动合并)

preload 脚本编译项预设：

• outDir：out\preload（相对于根目录）
• target：同主进程
• lib.entry：src\preload\{index|preload}.{js|ts|mjs|cjs}（相对于根目录），找不到则为空
• lib.formats：cjs
• rollupOptions.external：同主进程

渲染进程编译项预设：

• root：src\renderer（相对于根目录）
• outDir：out\renderer（相对于根目录）
• target：chrome*, 自动匹配 Electron 的 chrome 构建目标，如 Electron 17 为 chrome98
• lib.entry：src\renderer\index.html（相对于根目录），找不到则为空
• polyfillModulePreload：false，不需要为渲染进程 polyfill Module Preload
• rollupOptions.external：同主进程

主进程和 preload 脚本的 define 项设置：

在 Web 开发中，Vite 会将 'process.env.' 替换为 '({}).'，这是合理和正确的。但在 nodejs 开发中，我们有时候需要使用 process.env ，所以 electron-vite 重新预设全局变量替换，恢复其使用，预设如下：

export default {
  main: {
    define: {
      'process.env': 'process.env'
    }
  }
}

提示：如果你想在已有的项目中使用这些预设配置，可以使用 Vite 的插件 vite-plugin-electron-config

配置问题

如果 Electron 具有多窗口应该如何配置？

当 Electron 应用程序具有多窗口时，就意味着可能有多个 html 页面和 preload 脚本，你可以像下面一样修改你的配置文件：

export default {
  main: {},
  preload: {
    build: {
      rollupOptions: {
        input: {
          browser: resolve(__dirname, 'src/preload/browser.ts'),
          webview: resolve(__dirname, 'src/preload/webview.ts')
        }
      }
    }
  },
  renderer: {
    build: {
      rollupOptions: {
        input: {
          browser: resolve(__dirname, 'src/renderer/browser.html'),
          webview: resolve(__dirname, 'src/renderer/webview.html')
        }
      }
    }
  }
}

命令行选项

在项目中，可运行 npx electron-vite -h 获得完整的命令行选项列表。下面列出的标志只能通过命令行使用：

• --ignoreConfigWarning：boolean，忽略配置缺失警告（如配置文件中移除 preload 配置，不使用 preload 开发时，是有用的）
• --outDir：string，输出路径，相对根目录 (默认：out)

API

build

类型：

async function build(inlineConfig: InlineConfig = {}): Promise<void>

示例：

const path = require('path')
const { build } = require('electron-vite')

;(async () => {
  await build({
    build: {
      outDir: 'out'
      rollupOptions: {
        // ...
      }
    }
  })
})()

createServer

类型：

async function createServer(inlineConfig: InlineConfig = {}): Promise<void>

示例：

const { createServer } = require('electron-vite')

;(async () => {
  await createServer({
    server: {
      port: 1337
    }
  })
})()

preview

类型：

async function preview(inlineConfig: InlineConfig = {}): Promise<void>

示例：

const { preview } = require('electron-vite')

;(async () => {
  await preview({})
})()

InlineConfig

InlineConfig 接口扩展了 Vite UserConfig 并添加了以下属性：

• ignoreConfigWarning：设置为 false 来忽略配置缺失警告

同时移除 base 属性，因为在 Electron 中没有必要指定公共基础路径。

resolveConfig

类型：

async function resolveConfig(
  inlineConfig: InlineConfig,
  command: 'build' | 'serve',
  defaultMode = 'development'
): Promise<ResolvedConfig>

License

MIT © alex.wei