plugin-electron-ipc

为 Electron Vite 自动注册主进程 IPC 处理器、生成 preload 调用对象，并把主进程函数签名同步为渲染进程 TypeScript 类型。

安装

pnpm add plugin-electron-ipc

项目需要同时安装 electron、electron-vite 和 vite。

配置

同一组选项需要分别传给 Electron Vite 的 main 和 preload 构建：

// electron.vite.config.ts
import { defineConfig } from 'electron-vite';
import {
  createIpcChannelsPlugin,
  type IpcChannelsPluginOptions,
} from 'plugin-electron-ipc/vite';

// IPC 插件共享配置
const ipcOptions = {
  input: ['src/main/ipc/index.ts'],
  dts: 'src/plugin-electron-ipc.d.ts',
} satisfies IpcChannelsPluginOptions;

export default defineConfig({
  main: {
    plugins: [createIpcChannelsPlugin(ipcOptions)],
  },
  preload: {
    plugins: [createIpcChannelsPlugin(ipcOptions)],
  },
});

只复用 ipcOptions，不要把同一个插件实例同时放进 main 和 preload；两个构建需要各自调用一次 createIpcChannelsPlugin。

配置项

配置	类型	默认值	说明
input	string | readonly string[]	必传	导出 IPC 处理函数的一个或多个入口文件
dts	string	plugin-electron-ipc.d.ts	自动生成的渲染进程类型声明路径
tsconfig	string	自动查找 tsconfig.node.json	分析路径别名和具名重导出时使用的 TS 配置

所有路径都相对于 Vite 项目根目录。生成的 dts 文件需要被渲染进程的 tsconfig 包含；插件只在内容变化时更新它。

主进程处理器

第一个参数由 Electron 传入，渲染进程调用类型会自动移除它：

// src/main/ipc/index.ts
import type { IpcMainInvokeEvent } from 'electron';

// 打印渲染进程传入的内容
export const test = (_event: IpcMainInvokeEvent, content: string) => {
  console.log(content);
};

// 返回两数之和
export const sum = (
  _event: IpcMainInvokeEvent,
  left: number,
  right: number,
) => {
  return left + right;
};

插件会在主进程入口自动完成等价注册：

ipcMain.handle('test', test);
ipcMain.handle('sum', sum);

支持具名导出的箭头函数、函数表达式、函数声明以及具名重导出。非函数导出与默认导出会被忽略。on 是 preload 保留名称；导出 on 或从多个输入导出同名函数时，构建会直接报错。

preload

// src/preload/index.ts
import { contextBridge } from 'electron';
import { electronIpc, type ElectronIpc } from 'plugin-electron-ipc';

declare global {
  // 渲染进程可直接使用的类型安全 IPC 接口
  const ipc: ElectronIpc;
}

contextBridge.exposeInMainWorld('ipc', electronIpc);

electronIpc 是包含全部频道方法的普通可枚举对象，可以直接交给 contextBridge。所有频道方法都会返回 ipcRenderer.invoke 的 Promise。

渲染进程

ipc.test('打印我');

// 返回值类型为 Promise<number>
const total = await ipc.sum(1, 2);

固定提供事件订阅方法：

// 订阅主进程事件
const unsubscribe = ipc.on('show', () => {
  console.log('show');
});

unsubscribe();

限制

• 第一版仅适配 Electron Vite 5，并要求插件同时配置到 main 和 preload。
• IPC 处理器的第一个参数始终被视为 Electron 事件参数；需要接收业务参数时不要省略该占位参数。
• 自动类型声明会在 Electron Vite 开发或构建启动时生成，请确保声明路径已被渲染进程 TypeScript 配置包含。
• 根入口只能在 preload 构建中使用；Vite 配置必须从 plugin-electron-ipc/vite 导入插件。