首页
/ dromara/electron-egg 跨平台打包与分发完全指南

dromara/electron-egg 跨平台打包与分发完全指南

2026-02-05 04:08:17作者：邵娇湘
electron-egg
A simple, cross platform, enterprise desktop software development framework
项目地址：https://gitcode.com/dromara/electron-egg

你是否在开发桌面应用时，为不同操作系统的打包流程感到困扰？是否曾因配置错误导致应用在目标平台无法运行？本文将全面解析 electron-egg 框架的打包机制，从基础配置到高级优化，从 Windows 到 macOS 再到 Linux，带你掌握跨平台分发的核心技术，让你的企业级桌面应用轻松覆盖所有主流操作系统。读完本文，你将能够：配置多平台构建参数、优化打包体积、实现应用自动更新、解决常见兼容性问题，并了解企业级应用的签名与分发策略。

1. 框架打包架构概述

electron-egg 作为一款企业级桌面软件开发框架，提供了一套完整的跨平台打包解决方案。其核心基于 Electron Builder 实现，但通过自定义配置和封装脚本，极大简化了多平台构建流程。

1.1 打包工作流

打包流程主要分为三个阶段：前端资源构建、Electron 主进程处理和平台特定打包。整体流程如下：

flowchart TD
    A[开发完成] --> B[前端资源构建 npm run build-frontend]
    B --> C[Electron主进程处理 npm run build-electron]
    C --> D[代码加密 ee-bin encrypt]
    D --> E{选择目标平台}
    E -->|Windows| F[执行 npm run build-w]
    E -->|macOS| G[执行 npm run build-m]
    E -->|macOS ARM64| H[执行 npm run build-m-arm64]
    E -->|Linux| I[执行 npm run build-l]
    F --> J[生成NSIS安装包]
    G --> K[生成DMG镜像]
    H --> L[生成ARM架构DMG]
    I --> M[生成DEB包]
    J & K & L & M --> N[输出至out目录]

1.2 打包配置体系

框架采用分层配置策略，通过不同文件控制打包行为：

2. 打包前准备工作

2.1 环境要求

在开始打包前，请确保开发环境满足以下要求：

操作系统 最低配置要求 推荐配置
Windows Windows 10 64位，4GB内存，Node.js 14+ Windows 11 64位，8GB内存，Node.js 16+
macOS macOS 10.15+，4GB内存，Node.js 14+ macOS 12+，8GB内存，Node.js 16+
Linux Ubuntu 18.04+，4GB内存，Node.js 14+ Ubuntu 20.04+，8GB内存，Node.js 16+

2.2 项目构建

在执行打包命令前，需要先完成项目的完整构建：

# 安装依赖
npm install

# 执行完整构建
npm run build

该命令会依次完成：

  • 前端资源构建（基于 Vite）
  • Electron 主进程处理
  • 代码加密（保护核心逻辑）

构建完成后，检查以下目录是否生成正确：

  • public/dist：前端构建产物
  • public/electron：处理后的 Electron 主进程代码

3. Windows平台打包详解

Windows 平台是企业级应用的主要目标平台之一，electron-egg 提供了多种打包格式选择，满足不同场景需求。

3.1 基础打包（NSIS安装包）

NSIS（Nullsoft Scriptable Install System）是一个开源的 Windows 安装程序制作工具，electron-egg 默认使用此格式：

# 构建64位Windows安装包
npm run build-w

该命令对应的配置在 cmd/bin.js 中定义：

// cmd/bin.js 中 Windows 构建配置
win64: {
  cmd: 'electron-builder',
  directory: './',
  args: ['--config=./cmd/builder.json', '-w=nsis', '--x64'],
},

打包完成后，在 out 目录会生成类似 ee-win-4.1.0-x64.exe 的安装文件。

3.2 便携版打包

对于需要免安装运行的场景，可以构建便携版（Portable）：

# 构建64位Windows便携版
npm run build-we

对应配置：

// cmd/bin.js 中 Windows 便携版配置
win_e: {
  args: ['--config=./cmd/builder.json', '-w=portable', '--x64'],
},

便携版会生成一个可直接运行的文件夹，无需安装即可使用，适合企业内部测试或临时部署。

3.3 配置详解

Windows 平台的主要配置在 cmd/builder.json 中：

// Windows 平台关键配置
"win": {
  "icon": "build/icons/icon.ico",
  "artifactName": "${productName}-${os}-${version}-${arch}.${ext}",
  "target": [
    {
      "target": "nsis"
    }
  ]
},
"nsis": {
  "oneClick": false,
  "allowElevation": true,
  "allowToChangeInstallationDirectory": true,
  "installerIcon": "build/icons/icon.ico",
  "uninstallerIcon": "build/icons/icon.ico",
  "installerHeaderIcon": "build/icons/icon.ico",
  "createDesktopShortcut": true,
  "createStartMenuShortcut": true,
  "shortcutName": "ee"
}

关键配置项说明：

  • oneClick: 是否启用一键安装（不显示安装向导）
  • allowToChangeInstallationDirectory: 是否允许用户选择安装目录
  • createDesktopShortcut: 是否创建桌面快捷方式
  • artifactName: 定义输出文件名格式

3.4 常见问题解决

3.4.1 中文路径问题

若应用在中文路径下运行异常，可在 package.json 中添加：

"build": {
  "asarUnpack": ["**/*.dll", "**/*.node"]
}

3.4.2 应用图标不显示

确保 build/icons/icon.ico 文件存在且格式正确，建议使用 256x256 像素的图标文件。

4. macOS平台打包详解

macOS 平台打包需要在 macOS 系统上进行，主要生成 DMG 格式的安装文件。

4.1 Intel芯片与Apple Silicon芯片适配

electron-egg 同时支持 Intel 和 Apple Silicon (ARM64) 芯片的 Mac 设备：

# 构建Intel芯片版
npm run build-m

# 构建Apple Silicon芯片版
npm run build-m-arm64

对应的配置分别在 cmd/builder-mac.json 和 cmd/builder-mac-arm64.json 中定义。

4.2 配置详解

macOS 平台关键配置：

// cmd/builder-mac.json
"mac": {
  "icon": "build/icons/icon.icns",
  "artifactName": "${productName}-${os}-${version}-${arch}.${ext}",
  "darkModeSupport": true,
  "hardenedRuntime": false
}
  • darkModeSupport: 启用暗色模式支持
  • hardenedRuntime: 是否启用 macOS 强化运行时（用于应用签名）

4.3 应用签名

对于需要发布到 Mac App Store 或企业内部分发的应用，需要进行代码签名：

  1. 准备开发者证书
  2. 在打包命令中添加签名参数：
# 添加签名参数的构建命令
electron-builder --config=./cmd/builder-mac.json -m --arm64 \
  --sign --identity="Developer ID Application: Your Company (ABC123XYZ)"

4.4 打包结果

macOS 打包完成后，在 out 目录会生成：

  • DMG 安装镜像：ee-mac-4.1.0-x64.dmg
  • 应用文件夹：ee.app（可直接复制到 Applications 目录）

macOS应用界面示例

5. macOS ARM64平台打包

随着 Apple 芯片的普及，单独针对 ARM64 架构的打包支持变得尤为重要。

5.1 构建命令

# 构建Apple Silicon版本
npm run build-m-arm64

对应的配置在 cmd/bin.js 中：

mac_arm64: {
  args: ['--config=./cmd/builder-mac-arm64.json', '-m', '--arm64'],
},

5.2 配置特点

ARM64 配置 cmd/builder-mac-arm64.json 与 Intel 版本基本一致，但针对 ARM 架构做了优化：

"mac": {
  "icon": "build/icons/icon.icns",
  "artifactName": "${productName}-${os}-${version}-${arch}.${ext}",
  "darkModeSupport": true,
  "hardenedRuntime": false
}

5.3 兼容性考虑

为确保 ARM64 版本的兼容性，需注意：

  • 避免使用仅支持 x86 架构的 native 模块
  • 测试时使用真实 ARM64 设备或 Apple Silicon 模拟器
  • 对于必须的 x86 模块，考虑使用 Rosetta 转译或提供通用二进制版本

6. Linux平台打包详解

Linux 平台打包主要生成 DEB 格式安装包，适用于 Ubuntu、Debian 等主流发行版。

6.1 基础打包

# 构建64位Linux DEB包
npm run build-l

对应配置在 cmd/bin.js 中：

linux: {
  args: ['--config=./cmd/builder-linux.json', '-l=deb', '--x64'],
},

6.2 配置详解

Linux 平台配置在 cmd/builder-linux.json 中：

"linux": {
  "icon": "build/icons/icon.icns",
  "artifactName": "${productName}-${os}-${version}-${arch}.${ext}",
  "target": [
    "deb"
  ],
  "category": "Utility"
}
  • category: 指定应用类别，影响在 Linux 桌面环境中的分类显示
  • icon: Linux 平台同样支持 ICNS 格式图标

6.3 安装与测试

打包完成后，可通过以下命令安装测试：

# 安装DEB包
sudo dpkg -i out/ee-linux-4.1.0-x64.deb

# 运行应用
ee

Linux应用界面示例

6.4 ARM架构支持

对于树莓派等 ARM 架构设备，可构建 ARM64 版本：

// cmd/bin.js 中 Linux ARM64 配置
linux_arm64: {
  args: ['--config=./cmd/builder-linux.json', '-l=deb', '--arm64'],
},

7. 打包优化策略

随着应用功能增加，打包体积可能会显著增大，影响分发效率和用户体验。以下是几种有效的优化策略。

7.1 文件过滤配置

在打包配置中合理设置文件过滤，排除不必要的文件：

// builder.json 中的文件过滤配置
"files": [
  "**/*",
  "!cmd/",
  "!data/",
  "!electron/",
  "!frontend/",
  "!logs/",
  "!out/",
  "!go/",
  "!python/"
]

通过 ! 前缀排除开发环境文件和临时目录，仅保留运行时必需的资源。

7.2 资源压缩与混淆

electron-egg 内置了代码加密功能，可保护核心逻辑并减小体积：

# 单独执行加密命令
npm run encrypt

加密配置在 cmd/bin.js 中定义：

encrypt: {
  frontend: {
    type: 'none',
    files: [
      './public/dist/**/*.(js|json)',
    ],
    cleanFiles: ['./public/dist'],
    confusionOptions: {
      compact: true,      
      stringArray: true,
      stringArrayEncoding: ['none'],
      stringArrayCallsTransform: true,
      numbersToExpressions: true,
      target: 'browser',
    }
  },
  electron: {
    type: 'confusion',
    files: [
      './public/electron/**/*.(js|json)',
    ],
    cleanFiles: ['./public/electron'],
    specificFiles: [
      './public/electron/main.js',
      './public/electron/preload/bridge.js',
    ],
    confusionOptions: {
      compact: true,      
      stringArray: true,
      stringArrayEncoding: ['rc4'],
      deadCodeInjection: false,
      stringArrayCallsTransform: true,
      numbersToExpressions: true,
      target: 'node',
    }
  }
}

7.3 依赖优化

  • 使用 electron-builder 的 asar 功能打包应用代码：
// builder.json 中启用asar
"asar": true,
  • 检查并移除生产环境不需要的依赖：
# 安装生产依赖（移除devDependencies）
npm install --production

7.4 多平台构建对比

平台 构建产物大小 典型构建时间 主要优化点
Windows 80-120MB 3-8分钟 图标优化、NSIS压缩级别
macOS 90-130MB 4-10分钟 DMG压缩、代码签名优化
Linux 75-110MB 3-7分钟 DEB包压缩、依赖精简

8. 应用分发与自动更新

打包完成后，需要考虑如何高效分发给用户并支持后续更新。

8.1 分发渠道选择

企业级应用常见分发渠道：

  • 企业内部服务器（FTP/HTTP）
  • 专用应用商店（如微软商业商店、Mac App Store）
  • 第三方分发平台（如坚果云、蒲公英等）

8.2 自动更新配置

electron-egg 集成了 electron-updater 支持自动更新功能，配置位于 cmd/builder.json：

"publish": [
  {
    "provider": "generic",
    "url": "https://github.com/wallace5303/electron-egg"
  }
]

实际部署时，需将 url 修改为你的更新服务器地址。

8.3 版本管理策略

建议遵循语义化版本（Semantic Versioning）：

  • 主版本号（X.0.0）：不兼容的API变更
  • 次版本号（0.X.0）：向后兼容的功能新增
  • 修订号（0.0.X）：向后兼容的问题修正

版本号定义在 package.json 中：

{
  "name": "ee",
  "version": "4.1.0",
  // ...
}

9. 常见问题与解决方案

9.1 打包失败问题排查

当打包命令执行失败时，可按以下步骤排查：

  1. 检查日志：Electron Builder 会输出详细日志，关注 error 级别信息
  2. 验证配置：使用 JSON 验证工具检查配置文件格式
  3. 清理缓存：
# 清理npm缓存
npm cache clean --force

# 删除node_modules并重新安装
rm -rf node_modules package-lock.json
npm install
  1. 检查网络：确保网络通畅，electron-builder 需要下载平台特定依赖

9.2 应用运行问题

问题现象 可能原因 解决方案
应用启动后白屏 前端资源路径错误 检查 public/dist 是否存在，验证打包路径配置
主进程报错 主进程代码加密问题 尝试关闭加密重新打包测试
某些功能在特定平台失效 平台兼容性问题 检查是否使用了平台特定API，添加条件判断
应用体积过大 资源未优化 实施7.2节中的优化策略

9.3 企业级部署特殊需求

9.3.1 自定义安装路径

对于企业集中部署，可能需要指定固定安装路径，修改 cmd/builder.json：

"nsis": {
  "oneClick": true,
  "perMachine": true,
  "installDirectory": "C:\\Program Files\\YourCompany\\YourApp",
  // ...
}

9.3.2 静默安装

支持无交互静默安装：

# 静默安装命令
ee-setup.exe /S /D=C:\Program Files\YourApp

10. 企业级最佳实践

10.1 CI/CD集成

将打包流程集成到持续集成/持续部署管道，如 Jenkins、GitHub Actions 等：

# GitHub Actions 工作流示例（.github/workflows/build.yml）
name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [windows-latest, macos-latest, ubuntu-latest]
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
    
    - name: Install dependencies
      run: npm install
    
    - name: Build
      run: npm run build
    
    - name: Package
      run: |
        if [ "${{ matrix.os }}" == "windows-latest" ]; then
          npm run build-w
        elif [ "${{ matrix.os }}" == "macos-latest" ]; then
          npm run build-m
        else
          npm run build-l
        fi
    
    - name: Upload artifacts
      uses: actions/upload-artifact@v2
      with:
        name: ${{ matrix.os }}-build
        path: out/

10.2 多环境配置管理

对于开发、测试、生产等多环境，建议使用不同的配置文件：

electron/config/
├── config.default.js  # 默认配置
├── config.local.js    # 本地开发配置
└── config.prod.js     # 生产环境配置

通过命令行参数指定环境：

# 以生产环境启动
npm run start -- --env=prod

10.3 安全加固

企业级应用需特别关注安全性：

  1. 代码保护：启用 cmd/bin.js 中的加密功能
  2. 通信加密：确保应用与后端服务的通信使用 HTTPS
  3. 依赖审计：定期检查依赖安全问题
# 执行依赖安全审计
npm audit
  1. 最小权限原则：应用运行时仅申请必要的系统权限

11. 总结与展望

electron-egg 框架通过封装和优化 Electron Builder，提供了简洁高效的跨平台打包方案。本文详细介绍了 Windows、macOS 和 Linux 平台的打包流程、配置优化和分发策略，涵盖了从基础打包到企业级部署的各个方面。

随着桌面应用需求的不断发展，electron-egg 也在持续进化。未来版本可能会进一步优化构建速度、减小应用体积，并增强对新兴平台的支持。建议定期关注项目 README.md 和更新日志，及时获取最新功能和最佳实践。

掌握本文介绍的打包技术，你可以为企业构建出高质量、跨平台的桌面应用，同时大幅简化分发和维护流程。无论是内部业务系统还是面向客户的商业软件，electron-egg 都能提供坚实的技术支撑，让你专注于业务逻辑实现而非打包配置细节。

附录：常用命令速查表

命令 功能描述
npm run dev 启动开发环境
npm run build 执行完整构建（不含打包）
npm run build-w 构建Windows安装包
npm run build-we 构建Windows便携版
npm run build-m 构建macOS版
npm run build-m-arm64 构建macOS ARM64版
npm run build-l 构建Linux版
npm run start 以生产模式启动应用
npm run encrypt 执行代码加密
electron-egg
A simple, cross platform, enterprise desktop software development framework
项目地址：https://gitcode.com/dromara/electron-egg
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
27
11
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
525
3.72 K
pytorchpytorch
Ascend Extension for PyTorch
Python
332
395
flutter_flutterflutter_flutter
暂无简介
Dart
766
189
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
878
586
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
336
165
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
JavaScript
302
352
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
12
1
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.33 K
748
agent-studioagent-studio
openJiuwen agent-studio提供零码、低码可视化开发和工作流编排，模型、知识库、插件等各资源管理能力
TSX
985
246