electron-builder

electron-builder 用于把 Electron 构建产物打成平台安装包，例如 Windows NSIS、macOS DMG、Linux AppImage。

它通常接在 electron-vite build 之后：

electron-vite build
electron-builder

安装

pnpm add -D electron-builder

常见脚本：

{
  "scripts": {
    "build": "electron-vite build",
    "build:win": "pnpm build && electron-builder --win",
    "build:mac": "pnpm build && electron-builder --mac",
    "build:linux": "pnpm build && electron-builder --linux"
  }
}

基础配置

可以使用 electron-builder.yml：

appId: com.example.demo
productName: Demo App
copyright: Copyright © 2026 Example

directories:
  output: release
  buildResources: build

files:
  - out/**
  - package.json

asar: true

关键字段：

• appId：应用 ID，推荐使用反向域名格式。
• productName：应用展示名称。
• directories.output：安装包输出目录。
• directories.buildResources：图标、安装图等构建资源目录。
• files：进入应用包的文件。
• asar：是否把应用代码打包为 asar。

文件规则

files 决定哪些文件进入应用包：

files:
  - out/**
  - package.json
  - '!**/*.map'
  - '!**/test/**'
  - '!**/*.log'

extraResources 会把资源复制到应用资源目录，适合模型、数据库种子、二进制资源等：

extraResources:
  - from: resources/
    to: resources
    filter:
      - '**/*'
      - '!**/*.psd'

asarUnpack 用于解包不能放进 asar 的文件，常见于原生模块：

asar: true
asarUnpack:
  - '**/*.node'

Windows

win:
  target:
    - target: nsis
      arch:
        - x64
  icon: build/icon.ico
  executableName: demo-app
  requestedExecutionLevel: asInvoker

nsis:
  oneClick: false
  perMachine: false
  allowToChangeInstallationDirectory: true
  createDesktopShortcut: always
  shortcutName: Demo App
  uninstallDisplayName: Demo App
  artifactName: ${productName}-Setup-${version}.${ext}

常见选择：

• nsis：最常见的 Windows 安装器。
• oneClick: false：显示安装向导。
• perMachine: false：默认当前用户安装，减少管理员权限依赖。

macOS

mac:
  target:
    - target: dmg
      arch:
        - arm64
        - x64
    - zip
  icon: build/icon.icns
  category: public.app-category.developer-tools
  hardenedRuntime: true
  entitlements: build/entitlements.mac.plist
  entitlementsInherit: build/entitlements.mac.inherit.plist

注意：

• dmg 适合用户下载安装。
• zip 常用于自动更新。
• 正式分发通常需要代码签名和公证。
• universal 包体积更大，但可同时支持 Intel 和 Apple Silicon。

Linux

linux:
  target:
    - AppImage
    - deb
    - rpm
  icon: build/icons
  category: Utility
  synopsis: A short description
  description: A longer application description
  maintainer: Name <email>
  vendor: Example Studio

常见选择：

• AppImage：分发简单，适合通用下载。
• deb：适合 Debian / Ubuntu 系。
• rpm：适合 Fedora / RHEL 系。

原生模块

如果项目使用 better-sqlite3、sharp 等原生模块，需要针对 Electron 的 ABI 重建。

{
  "scripts": {
    "postinstall": "electron-builder install-app-deps"
  }
}

npmRebuild: true

pnpm 可能会跳过依赖构建脚本，需要显式允许：

{
  "pnpm": {
    "onlyBuiltDependencies": ["better-sqlite3", "electron", "esbuild"]
  }
}

发布

发布目标可以配置为 GitHub Releases：

publish:
  - provider: github
    owner: example
    repo: demo-app
    releaseType: draft

签名、公证、自动更新和 CI 流程强相关，建议在基础打包稳定后单独维护。

Checklist

• [ ] 配置 appId、productName、图标和输出目录
• [ ] 确认 files 只包含运行必需文件
• [ ] 原生模块配置 install-app-deps、npmRebuild、asarUnpack
• [ ] Windows 配置 nsis
• [ ] macOS 准备签名、公证和 entitlements
• [ ] Linux 按分发渠道选择 AppImage、deb、rpm