编程马·菜鸟教程

Appearance

第13章：Electron 应用打包 ​

13.1 打包工具选择 ​

在 Electron 应用开发中，有多种打包工具可供选择，其中最常用的是 electron-builder 和 electron-packager。

13.1.1 electron-builder ​

特点：

  • 功能强大，支持多平台打包（Windows、Mac、Linux）
  • 支持自动更新功能
  • 支持代码签名
  • 支持创建安装程序
  • 配置灵活，可定制性高

适用场景：

  • 需要跨平台发布的应用
  • 需要专业安装体验的应用
  • 企业级应用开发

13.1.2 electron-packager ​

特点：

  • 简单易用，适合快速打包
  • 配置相对简单
  • 生成的是可执行文件，不包含安装程序

适用场景：

  • 快速开发和测试
  • 内部工具和原型
  • 不需要复杂安装流程的应用

13.2 打包配置 ​

13.2.1 package.json 配置 ​

使用 electron-builder 时，需要在 package.json 中添加打包配置：

json
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "My Electron application",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build": "electron-builder"
  },
  "devDependencies": {
    "electron": "^18.0.0",
    "electron-builder": "^22.14.5"
  },
  "build": {
    "appId": "com.example.app",
    "productName": "My Application",
    "copyright": "Copyright © 2023 ${author}",
    "directories": {
      "output": "dist"
    },
    "files": [
      "main.js",
      "index.html",
      "package.json",
      "assets/**/*"
    ],
    "mac": {
      "category": "public.app-category.utilities",
      "icon": "assets/icon.icns"
    },
    "win": {
      "target": [
        "nsis",
        "portable"
      ],
      "icon": "assets/icon.ico"
    },
    "linux": {
      "target": [
        "deb",
        "rpm",
        "AppImage"
      ],
      "icon": "assets/icon.png"
    }
  }
}

13.2.2 配置说明 ​

  • appId：应用的唯一标识符，通常使用反向域名格式
  • productName：应用的显示名称
  • copyright：版权信息
  • directories.output：打包输出目录
  • files：需要打包的文件和目录
  • mac：macOS 特定配置
  • win：Windows 特定配置
  • linux：Linux 特定配置

13.2.3 图标配置 ​

不同平台需要不同格式的图标：

  • Windows：.ico 格式，推荐尺寸 256x256
  • macOS：.icns 格式，包含多种尺寸
  • Linux：.png 格式，推荐尺寸 512x512

13.3 多平台打包实操 ​

13.3.1 Windows 打包 ​

13.3.1.1 生成 exe 安装包 ​

  1. 安装依赖

    bash
    npm install electron-builder --save-dev

  2. 修改 package.json

    json
    {
  "scripts": {
    "build:win": "electron-builder --win"
  },
  "build": {
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico"
    }
  }
}

  3. 执行打包

    bash
    npm run build:win

  4. 输出结果

    • dist/My Application Setup 1.0.0.exe：安装程序
    • dist/win-unpacked/：未打包的可执行文件

13.3.1.2 生成便携版 ​

  1. 修改 package.json

    json
    {
  "build": {
    "win": {
      "target": "portable",
      "icon": "assets/icon.ico"
    }
  }
}

  2. 执行打包

    bash
    npm run build:win

  3. 输出结果

    • dist/My Application 1.0.0.exe：便携版可执行文件

13.3.2 macOS 打包 ​

  1. 修改 package.json

    json
    {
  "scripts": {
    "build:mac": "electron-builder --mac"
  },
  "build": {
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns"
    }
  }
}

  2. 执行打包

    bash
    npm run build:mac

  3. 输出结果

    • dist/My Application-1.0.0.dmg：DMG 安装包
    • dist/mac/：未打包的应用

13.3.3 Linux 打包 ​

  1. 修改 package.json

    json
    {
  "scripts": {
    "build:linux": "electron-builder --linux"
  },
  "build": {
    "linux": {
      "target": ["deb", "rpm", "AppImage"],
      "icon": "assets/icon.png"
    }
  }
}

  2. 执行打包

    bash
    npm run build:linux

  3. 输出结果

    • dist/My Application-1.0.0.deb：Debian 包
    • dist/My Application-1.0.0.rpm：RPM 包
    • dist/My Application-1.0.0.AppImage：AppImage 可执行文件

13.3.4 跨平台打包 ​

在 macOS 上，可以同时打包 Windows 和 Linux 版本：

  1. 修改 package.json

    json
    {
  "scripts": {
    "build:all": "electron-builder -mwl"
  }
}

  2. 执行打包

    bash
    npm run build:all

13.4 打包常见问题排查 ​

13.4.1 打包失败 ​

常见原因：

  • 依赖安装失败
  • 配置错误
  • 资源文件缺失
  • 权限不足

排查方法：

  • 检查控制台输出的错误信息
  • 确保所有依赖都已正确安装
  • 检查打包配置是否正确
  • 确保资源文件路径正确

13.4.2 图标不显示 ​

常见原因：

  • 图标文件格式不正确
  • 图标文件路径错误
  • 图标尺寸不符合要求

排查方法：

  • 确保使用正确格式的图标文件
  • 检查图标文件路径是否正确
  • 确保图标尺寸符合平台要求

13.4.3 应用无法启动 ​

常见原因：

  • 主进程文件路径错误
  • 依赖缺失
  • 权限问题
  • 代码错误

排查方法：

  • 检查主进程文件路径是否正确
  • 确保所有依赖都已正确打包
  • 检查应用权限设置
  • 查看应用日志文件

13.4.4 白屏问题 ​

常见原因：

  • 渲染进程加载失败
  • 页面路径错误
  • 代码错误

排查方法：

  • 检查渲染进程代码是否有错误
  • 确保页面文件路径正确
  • 查看开发者工具控制台输出

13.5 应用签名 ​

13.5.1 Windows 签名 ​

为什么需要签名：

  • 避免系统安全提示
  • 提高应用可信度
  • 符合企业安全要求

签名步骤：

  1. 获取代码签名证书

    • 从证书颁发机构购买
    • 使用自签名证书（仅用于测试）

  2. 配置签名

    json
    {
  "build": {
    "win": {
      "certificateFile": "path/to/certificate.pfx",
      "certificatePassword": "your-password"
    }
  }
}

  3. 执行签名

    bash
    npm run build:win

13.5.2 macOS 签名 ​

为什么需要签名：

  • 避免 Gatekeeper 阻止
  • 提高应用可信度
  • 符合 App Store 要求

签名步骤：

  1. 获取开发者证书

    • 在 Apple Developer Portal 申请

  2. 配置签名

    json
    {
  "build": {
    "mac": {
      "identity": "Developer ID Application: Your Name (TEAMID)"
    }
  }
}

  3. 执行签名

    bash
    npm run build:mac

13.5.3 公证（Notarization） ​

在 macOS Catalina 及以上版本，还需要对应用进行公证：

json
{
  "build": {
    "mac": {
      "notarize": {
        "appleId": "your-apple-id",
        "appleIdPassword": "your-apple-id-password"
      }
    }
  }
}

13.6 实操案例：打包 Electron 应用 ​

13.6.1 场景描述 ​

创建一个简单的 Electron 应用，并使用 electron-builder 进行打包，生成 Windows、macOS 和 Linux 版本。

13.6.2 实现步骤 ​

  1. 创建项目结构

打包示例/ ├── main.js ├── index.html ├── package.json └── assets/ ├── icon.ico ├── icon.icns └── icon.png


2. **修改 package.json**

```json
{
  "name": "electron-packaging-example",
  "version": "1.0.0",
  "description": "Electron 打包示例",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build": "electron-builder",
    "build:win": "electron-builder --win",
    "build:mac": "electron-builder --mac",
    "build:linux": "electron-builder --linux",
    "build:all": "electron-builder -mwl"
  },
  "devDependencies": {
    "electron": "^18.0.0",
    "electron-builder": "^22.14.5"
  },
  "build": {
    "appId": "com.example.packaging",
    "productName": "Electron 打包示例",
    "copyright": "Copyright © 2023 Example",
    "directories": {
      "output": "dist"
    },
    "files": [
      "main.js",
      "index.html",
      "package.json",
      "assets/**/*"
    ],
    "mac": {
      "category": "public.app-category.utilities",
      "icon": "assets/icon.icns"
    },
    "win": {
      "target": [
        "nsis",
        "portable"
      ],
      "icon": "assets/icon.ico"
    },
    "linux": {
      "target": [
        "deb",
        "rpm",
        "AppImage"
      ],
      "icon": "assets/icon.png"
    }
  }
}

  1. 修改 main.js

    javascript
    const { app, BrowserWindow } = require('electron')
const path = require('path')

function createWindow() {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    }
  })

  win.loadFile('index.html')
}

app.whenReady().then(createWindow)

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})

app.on('activate', function () {
  if (BrowserWindow.getAllWindows().length === 0) createWindow()
})

  2. 修改 index.html

    html
    <!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Electron 打包示例</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 20px;
      padding: 0;
      background-color: #f0f0f0;
    }
    .container {
      max-width: 600px;
      margin: 0 auto;
      background-color: white;
      padding: 20px;
      border-radius: 8px;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
    }
    h1 {
      color: #333;
      text-align: center;
    }
    p {
      line-height: 1.6;
      color: #666;
    }
    .version {
      text-align: center;
      margin-top: 30px;
      font-size: 14px;
      color: #999;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Electron 打包示例</h1>
    <p>这是一个用于演示 Electron 应用打包的示例应用。</p>
    <p>通过 electron-builder，我们可以将这个应用打包为：</p>
    <ul>
      <li>Windows：.exe 安装包和便携版</li>
      <li>macOS：.dmg 安装包</li>
      <li>Linux：.deb、.rpm 和 AppImage</li>
    </ul>
    <div class="version">版本：1.0.0</div>
  </div>
</body>
</html>

  3. 准备图标文件

    • assets/icon.ico：Windows 图标
    • assets/icon.icns：macOS 图标
    • assets/icon.png：Linux 图标

  4. 安装依赖

    bash
    npm install

  5. 执行打包

    • Windows 打包：npm run build:win
    • macOS 打包：npm run build:mac
    • Linux 打包：npm run build:linux
    • 全平台打包：npm run build:all

  6. 查看输出

    打包完成后，在 dist 目录中可以看到生成的安装包和可执行文件。

13.7 小结 ​

通过本章的学习，你已经掌握了 Electron 应用打包的核心知识：

  • 打包工具选择：了解了 electron-builder 和 electron-packager 的特点和适用场景
  • 打包配置：学习了如何在 package.json 中配置打包参数
  • 多平台打包：掌握了如何为 Windows、macOS 和 Linux 平台打包应用
  • 常见问题排查：了解了打包过程中常见的问题和解决方法
  • 应用签名：学习了如何为应用进行代码签名，提高应用可信度

打包是 Electron 应用开发的重要环节，一个成功的打包流程可以确保应用能够在不同平台上顺利运行，为用户提供良好的安装和使用体验。

© 2026 编程马·菜鸟教程 版权所有

基于 VitePress 构建