打包与分发

打包工具选择

electron-builder vs electron-forge

本章主要介绍 electron-builder，因其功能更全面、文档更完善。

安装 electron-builder

npm install --save-dev electron-builder

基础 package.json 配置

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "My Electron Application",
  "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": {
    "appId": "com.example.my-app",
    "productName": "My App",
    "directories": {
      "output": "dist"
    },
    "files": [
      "main.js",
      "preload.js",
      "src/**/*",
      "assets/**/*"
    ]
  }
}

macOS 打包配置

基础配置

{
  "build": {
    "mac": {
      "category": "public.app-category.productivity",
      "target": [
        {
          "target": "dmg",
          "arch": ["x64", "arm64"]
        },
        {
          "target": "zip",
          "arch": ["x64", "arm64"]
        }
      ],
      "icon": "assets/icon.icns",
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "assets/entitlements.plist",
      "entitlementsInherit": "assets/entitlements-inherit.plist"
    }
  }
}

macOS 签名配置

{
  "build": {
    "mac": {
      "identity": "Developer ID Application: Your Name (TEAM_ID)",
      "signingHash": "sha256"
    }
  }
}

使用环境变量进行签名

// 在 CI/CD 环境中使用
// process.env.CERTIFICATE_ID 或 process.env.APPLE_ID

notarize（公证）配置

macOS 10.15+ 需要公证才能分发：

{
  "build": {
    "mac": {
      "notarize": {
        "appleId": "[email protected]",
        "appleIdPassword": "@keychain:AC_PASSWORD",
        "teamId": "YOUR_TEAM_ID"
      }
    }
  }
}

Windows 打包配置

基础配置

{
  "build": {
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64"]
        },
        {
          "target": "portable",
          "arch": ["x64"]
        }
      ],
      "icon": "assets/icon.ico",
      "artifactName": "${productName}-${version}-Setup.${ext}"
    }
  }
}

NSIS 安装程序配置

{
  "build": {
    "nsis": {
      "oneClick": false,
      "perMachine": false,
      "allowToChangeInstallationDirectory": true,
      "deleteAppDataOnUninstall": false,
      "installerIcon": "assets/installer-icon.ico",
      "uninstallerIcon": "assets/uninstaller-icon.ico",
      "installerHeaderIcon": "assets/installer-header.ico",
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true,
      "shortcutName": "My App"
    }
  }
}

Windows 签名配置

{
  "build": {
    "win": {
      "certificateFile": "./certs/certificate.pfx",
      "certificatePassword": "your-password",
      "signingHash": "sha256"
    }
  }
}

使用 Azure SignTool（企业签名）

{
  "build": {
    "win": {
      "signingServer": {
        "url": "https://your-signing-server/api/sign",
        "tokenEnv": "AZURE_SIGN_TOKEN"
      }
    }
  }
}

Linux 打包配置

{
  "build": {
    "linux": {
      "target": [
        {
          "target": "AppImage",
          "arch": ["x64"]
        },
        {
          "target": "deb",
          "arch": ["x64"]
        },
        {
          "target": "rpm",
          "arch": ["x64"]
        }
      ],
      "category": "Office",
      "icon": "assets/icons",
      "mimeTypes": ["application/pdf"]
    }
  }
}

AppImage 配置

{
  "build": {
    "appImage": {
      "artifactName": "${productName}-${version}.${ext}"
    }
  }
}

deb 包配置

{
  "build": {
    "deb": {
      "maintainer": "Your Name <[email protected]>",
      "homepage": "https://example.com",
      "depends": [
        "libgtk-3-0",
        "libnotify4",
        "libnss3"
      ]
    }
  }
}

多平台构建

同时构建多个平台

# 构建所有平台
npm run build

# 或指定平台
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux

在 CI/CD 中构建

GitHub Actions

# .github/workflows/build.yml
name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: linux
          - os: macos-latest
            target: mac
          - os: windows-latest
            target: win

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build:${{ matrix.target }}
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
          CERTIFICATE_ID: ${{ secrets.CERTIFICATE_ID }}

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.target }}-build
          path: dist/

应用分发

1. GitHub Releases

{
  "build": {
    "github": {
      "owner": "your-username",
      "repo": "your-repo",
      "release": true
    }
  }
}

2. 私有分发服务器

{
  "build": {
    "publish": [
      {
        "provider": "generic",
        "url": "https://update.example.com/releases/"
      }
    ]
  }
}

3. S3/云存储分发

{
  "build": {
    "publish": [
      {
        "provider": "s3",
        "bucket": "your-bucket",
        "region": "us-east-1",
        "path": "/releases/"
      }
    ]
  }
}

构建优化

排除不需要的文件

{
  "build": {
    "files": [
      "!node_modules/**/*",
      "node_modules/required-package/**/*"
    ],
    "extraResources": [
      {
        "from": "resources/",
        "to": "resources/",
        "filter": ["**/*"]
      }
    ],
    "asar": true,
    "asarUnpack": [
      "**/*.node"
    ]
  }
}

压缩级别

{
  "build": {
    "compression": "maximum"  // store, normal, maximum
  }
}

删除源码

{
  "build": {
    "npmPrune": true,
    "npmRebuild": true
  }
}

常见问题

1. 应用无法启动

检查：

• main 入口是否正确
• 是否缺少依赖
• 路径是否正确

2. macOS "应用已损坏"

需要签名或禁用 Gatekeeper：

xattr -cr /path/to/app.app

3. Windows 杀毒软件误报

• 使用代码签名
• 在发布说明中说明
• 提交到杀毒软件白名单

4. Linux 桌面图标不显示

{
  "build": {
    "linux": {
      "desktop": {
        "MimeType": "x-scheme-handler/myapp"
      }
    }
  }
}

这一章想说的

Electron 打包与分发：

1. electron-builder：最流行的打包工具
2. 多平台配置：macOS（签名、公证）、Windows（NSIS）、Linux（AppImage）
3. 代码签名：确保应用被系统信任
4. 分发方式：GitHub Releases、私有服务器、S3
5. CI/CD：自动化构建流程

完善的打包和分发流程是桌面应用成功的关键。

延展阅读

• electron-builder
• electron-builder 配置
• Code Signing
• Publishing Artifacts