如何配置 CI/CD 流水线自动构建 Electron 多平台安装包

基于 GitHub Actions 配合 electron-builder 的矩阵策略，能在同一仓库流程中并行产出 Windows、macOS 和 Linux 安装包。以下是经过生产验证的配置方案，重点解决了代码签名、原生模块编译及 CI 超时问题。

先说结论：使用原生操作系统 runner 分别构建对应平台安装包是最稳妥的方案，避免跨平台编译带来的 native 模块兼容问题。

适合：需要定期发布更新且多平台用户占比均衡的项目
先准备：各平台代码签名证书及 CI 环境变量配置
验收：构建完成后下载产物并在对应系统上安装运行

1. 项目配置文件准备

在 package.json 中配置构建脚本，确保 electron-builder 能识别当前环境。建议单独配置 build 命令以便 CI 调用。

"scripts": {
  "build": "electron-builder",
  "build:win": "electron-builder `--win`",
  "build:mac": "electron-builder `--mac`",
  "build:linux": "electron-builder `--linux`"
}

同时，根目录下需存在 electron-builder 配置文件（electron-builder.yml 或 package.json 中的 build 字段），明确指定多平台产物格式。

build:
  appId: com.example.app
  productName: MyElectronApp
  directories:
    output: dist
  mac:
    target: dmg
    identity: null
  win:
    target: nsis
  linux:
    target: AppImage

2. GitHub Actions Workflow 完整配置

在 .github/workflows 下新建 build.yml。以下配置包含节点缓存、矩阵策略及产物上传，能有效避免 CI 超时。

name: Build Electron App

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    strategy:
      matrix:
        os: [windows-latest, macos-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install Dependencies
        run: npm ci
      
      - name: Build
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
        run: npm run build
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.os }}-dist
          path: dist/
          retention-days: 5

3. 代码签名与 Notarization 配置

代码签名是分发应用的关键步骤，尤其是 macOS 外部分发必须经过 notarization（公证）。

Windows 签名：将 .p12 证书文件进行 Base64 编码，存入 Secrets 作为 CSC_LINK，密码存入 CSC_KEY_PASSWORD。

macOS 签名与公证：除了 CSC 相关变量外，必须配置 APPLE_ID 和 APPLE_APP_SPECIFIC_PASSWORD。electron-builder 会在构建完成后自动提交公证请求。注意 Apple ID 密码需使用"应用专用密码"，而非登录密码。

安全提示：切勿将证书文件或密码硬编码在 YAML 文件中，所有敏感信息必须通过 GitHub Secrets 传递。

4. 验证构建结果

构建完成后，按以下步骤验收：

检查日志：确认 GitHub Actions 每个矩阵任务状态为绿色，无 red 报错。
下载产物：在 Actions 页面底部下载对应系统的 Artifacts 压缩包。
本地安装：在对应操作系统上解压并安装，启动应用。
控制台检查：打开开发者工具（F12），确认 Console 无原生模块加载错误（如 .node 文件缺失）。
签名验证（macOS）：终端运行 xattr -d com.apple.quarantine /Applications/MyElectronApp.app 后启动，确认无安全警告拦截。

5. 常见坑与排查

1. CI 构建超时：node_modules 过大是主因。务必启用 setup-node 的 cache 功能（如上配置所示），缓存 key 默认基于 package-lock.json 生成。

2. 原生模块编译失败：若使用 serialport、sqlite3 等模块，CI 环境需安装构建工具。Windows 需确保包含 Visual Studio Build Tools，Linux/macOS 通常预装 Python 和 Make，但需确认版本兼容性。可在 install 步骤前添加 npm install `--build-from-source`。

3. macOS 公证失败：常见原因是 APPLE_APP_SPECIFIC_PASSWORD 错误或未启用双重认证。需在 Apple ID 账户设置中生成专用密码，并确保构建产物 Bundle ID 与证书匹配。

4. 路径大小写问题：Windows 对路径大小写不敏感，但 Linux 敏感。代码中引用资源路径时务必保持与实际文件一致，避免本地开发正常但 Linux CI 报错。