electron

Electron Forge 开发环境与项目配置

By AI-Writer 8 min read

前言

Electron Forge 是 Electron 官方推荐的脚手架和打包工具链，解决了手动配置 Electron 项目时的繁琐和坑点。它整合了 Webpack、Vite、esbuild 等多种构建方式，并内置了打包、分发、代码签名等生产级功能。本文将全面介绍如何用 Electron Forge 搭建高效的开发环境。

环境准备

必要工具

bash
# Node.js >= 18.0（推荐 20 LTS）
node -v

# pnpm（比 npm 更快，推荐）
corepack enable pnpm
pnpm -v

# Git
git -v

Electron Forge 脚手架

Electron Forge 提供多种模板：

模板适用场景构建工具
vite新项目首选，快Vite
webpack需要精细控制构建流程Webpack
esbuild极致的构建速度esbuild
vite-typescriptTypeScript 项目Vite + TS
bash
# 创建 Vite + TypeScript 项目
pnpm create electron-app@latest my-app --template=vite-typescript

cd my-app
pnpm install
pnpm dev

创建完成后，项目目录结构如下：

plaintext
my-app/
├── package.json
├── forge.config.js       ← Forge 打包配置
├── vite.main.config.mjs  ← 主进程构建配置
├── vite.preload.config.mjs
├── vite.renderer.config.mjs
├── src/
│   ├── main.ts            ← 主进程入口
│   ├── preload.ts         ← 预加载脚本
│   └── renderer/         ← 渲染进程代码（Vite 入口）
│       ├── index.html
│       ├── main.ts
│       └── styles.css
└── resources/            ← 应用图标等资源

package.json 关键字段

Electron 项目的 package.json 有几个 Electron 特有的关键字段：

json
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "我的 Electron 应用",

  "main": ".vite/build/main.js",
  "author": "Your Name",
  "license": "MIT",

  "scripts": {
    "start": "electron-forge start",    // 开发启动
    "package": "electron-forge package", // 打包（不生成安装包）
    "make": "electron-forge make",       // 生成平台安装包
    "publish": "electron-forge publish"  // 发布
  },

  "devDependencies": {
    "@electron-forge/cli": "^7.0.0",
    "@electron-forge/maker-squirrel": "^7.0.0",
    "@electron-forge/maker-zip": "^7.0.0",
    "electron": "^35.0.0"
  }
}

main 字段指向主进程的入口文件，必须准确。**scripts.start**是开发启动命令，使用 electron-forge start 会自动处理构建和启动。

Forge 配置详解

javascript
// forge.config.js
const { Fuses } = require('@electron-forge/plugin-fuses');
const { FuseV1Options, FuseVersion } = require('@electron/fuses');

module.exports = {
  packagerConfig: {
    name: 'MyElectronApp',
    executableName: 'my-electron-app',
    asar: true,
    icon: './resources/icon',
    // macOS 应用签名
    osxSign: {},
    // Windows 图标（需为 ico 格式）
    win32metadata: {
      CompanyName: 'My Company',
      FileDescription: 'My Electron App',
      ProductName: 'MyElectronApp',
    },
  },

  rebuildConfig: {},

  makers: [
    // Windows: Squirrel 安装包
    new MakerSquirrel({
      name: 'MyElectronApp',
      setupIcon: './resources/icon.ico',
    }),
    // macOS: DMG 镜像
    new MakerDMG({
      name: 'MyElectronApp',
      icon: './resources/icon.icns',
    }),
    // Linux: zip
    new MakerZIP({}, ['darwin', 'linux']),
  ],

  plugins: [
    {
      name: '@electron-forge/plugin-auto-unpack-natives',
      config: {},
    },
    // Vite 插件
    new VitePlugin({
      build: [
        {
          entry: 'src/main.ts',
          config: 'vite.main.config.mjs',
          target: 'main',
        },
        {
          entry: 'src/preload.ts',
          config: 'vite.preload.config.mjs',
          target: 'preload',
        },
      ],
      renderer: [
        {
          name: 'main_window',
          config: 'vite.renderer.config.mjs',
        },
      ],
    }),
    // Electron Fuses 安全加固
    new Fuses({
      version: FuseVersion.V1,
      [FuseV1Options.RunAsNode]: false,
      [FuseV1Options.EnableCookieEncryption]: true,
      [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false,
      [FuseV1Options.EnableNodeCliInspectArguments]: false,
      [FuseV1Options.EnableEmbeddedAsarIntegrityValidation]: true,
      [FuseV1Options.OnlyLoadAppFromAsar]: true,
    }),
  ],
};

Vite 配置（主进程）

javascript
// vite.main.config.mjs
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    outDir: '.vite/build',
    lib: {
      entry: 'src/main.ts',
      formats: ['cjs'],
      fileName: () => 'main.js',
    },
    rollupOptions: {
      external: ['electron', 'electron-log', 'path', 'fs', 'os'],
    },
    minify: false,  // 开发环境不压缩，便于调试
  },
});

开发调试

热重载

使用 Vite 模板时，渲染进程默认支持热模块替换（HMR）——修改前端代码无需重启整个应用，主进程代码修改后会触发自动重启。

bash
# 启动开发服务器
pnpm dev

DevTools 调试

在渲染进程中打开 DevTools：

typescript
// src/main.ts
import { BrowserWindow } from 'electron';

const win = new BrowserWindow({ width: 1200, height: 800 });

// 启动时打开 DevTools（仅开发模式）
if (process.env.NODE_ENV === 'development') {
  win.webContents.openDevTools();
}

主进程断点调试

Electron Forge + VS Code 配置断点调试：

json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": ["."],
      "outputCapture": "std",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

设置断点后按 F5 即可在主进程中逐行调试。

生产日志排查

渲染进程崩溃或异常时，使用 electron-log 收集日志：

typescript
// src/main.ts
import log from 'electron-log';

// 主进程日志
log.info('应用启动');
log.error('出错了', error);

// 捕获未处理的异常
process.on('uncaughtException', (error) => {
  log.error('未捕获异常:', error);
});

process.on('unhandledRejection', (reason) => {
  log.error('未处理的 Promise 拒绝:', reason);
});

// 渲染进程日志（需要 IPC）
log.info('渲染进程日志来自:', win.webContents.getURL());

项目规范化

目录结构约定

plaintext
src/
├── main.ts           # 主进程入口（应用生命周期管理）
├── preload.ts        # 预加载脚本（安全的 IPC 桥接）
├── renderer/         # 渲染进程代码（前端）
│   ├── index.html
│   ├── main.ts       # 前端入口
│   ├── App.vue       # 或 App.tsx
│   └── styles/
├── ipc/              # IPC 处理函数（可分离）
│   └── handlers.ts
└── shared/           # 主进程和渲染进程共享类型
    └── types.ts

TypeScript 配置

json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", ".vite"]
}

常见问题

macOS 启动报错 “Electron failed to install correctly”

bash
# 重新安装 Electron
pnpm rebuild electron

Windows 上 electron 命令找不到

bash
# 确认 node_modules/.bin 在 PATH 中
npx electron .

pnpm 安装后运行报错

Electron 原生模块（node-gyp 编译）在 pnpm 下需要特殊处理：

bash
pnpm add electron -D
pnpm rebuild

或在 package.json 中添加：

json
{
  "pnpm": {
    "onlyBuiltDependencies": ["electron"]
  }
}

小结

  • Electron Forge 是 Electron 官方推荐的脚手架和打包工具
  • Vite 模板是新建项目的最佳选择，内置热重载和快速构建
  • package.json 的 main、scripts 字段是 Electron 项目的核心配置
  • forge.config.js 控制打包行为、Makers（安装包格式）和安全加固选项
  • 生产构建使用 pnpm make，开发调试使用 pnpm dev

下一篇文章我们将深入讲解 IPC 通信机制，掌握主进程与渲染进程之间双向异步通信的核心方法。

#electron #electron-forge #vite #webpack #开发环境

评论

A

Written by

AI-Writer

Related Articles

electron
#9

Electron 应用打包与分发

使用 electron-builder 配置多平台打包（Windows NSIS / macOS DMG / Linux AppImage），设置自动更新（electron-updater），配置代码签名（Authenticode / Apple Developer），搭建 GitHub Actions CI 流水线

Read More
electron
#7

Node.js 原生模块调用

在 Electron 主进程中使用 npm 原生模块（sqlite3、sharp），Native Module 编译（node-gyp / electron-rebuild），纯 JS 替代方案以及多线程 Worker Threads 实践

Read More
electron
#8

React / Vue 与 Electron 集成

使用 electron-vite 工具链整合 Vite + React/Vue + Electron，配置路由（React Router / Vue Router），实现主进程与渲染进程状态共享（Zustand IPC 桥接）

Read More
Back to All Articles