多平台构建 #

一、跨平台概述 #

1.1 平台差异 #

平台	安装包格式	架构	签名
Windows	exe, msi	x64, ia32	代码签名证书
macOS	dmg, zip, pkg	x64, arm64	Developer ID
Linux	AppImage, deb, rpm, snap	x64, arm64	可选

1.2 构建策略 #

text

┌─────────────────────────────────────────────────────────────┐
│                    跨平台构建策略                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  方式一：本地构建                                            │
│  ├── macOS 主机 → macOS 安装包                              │
│  ├── Windows 主机 → Windows 安装包                          │
│  └── Linux 主机 → Linux 安装包                              │
│                                                             │
│  方式二：CI/CD 构建                                          │
│  ├── GitHub Actions → 所有平台                              │
│  ├── GitLab CI → 所有平台                                   │
│  └── Travis CI → 所有平台                                   │
│                                                             │
│  方式三：Docker 构建                                         │
│  └── Linux 容器 → Linux 安装包                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

二、本地构建 #

2.1 macOS 构建 #

bash

# 构建 macOS
npm run build:mac

# 构建指定架构
electron-builder --mac --x64
electron-builder --mac --arm64

# 构建通用二进制
electron-builder --mac --universal

yaml

# electron-builder.yml
mac:
    target:
        - target: dmg
          arch:
              - x64
              - arm64
        - target: zip
          arch:
              - x64
              - arm64

2.2 Windows 构建 #

bash

# 在 Windows 上构建
npm run build:win

# 在 macOS/Linux 上交叉编译
electron-builder --win --x64

# 构建多种格式
electron-builder --win nsis portable

yaml

# electron-builder.yml
win:
    target:
        - target: nsis
          arch:
              - x64
              - ia32
        - target: portable
          arch:
              - x64

2.3 Linux 构建 #

bash

# 构建 Linux
npm run build:linux

# 构建指定格式
electron-builder --linux AppImage
electron-builder --linux deb
electron-builder --linux rpm

yaml

# electron-builder.yml
linux:
    target:
        - target: AppImage
          arch:
              - x64
              - arm64
        - target: deb
          arch:
              - x64
        - target: rpm
          arch:
              - x64

三、CI/CD 构建 #

3.1 GitHub Actions 完整配置 #

yaml

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

on:
    push:
        tags:
            - 'v*'
    workflow_dispatch:

jobs:
    build:
        strategy:
            matrix:
                include:
                    - os: macos-latest
                      platform: mac
                    - os: windows-latest
                      platform: win
                    - os: ubuntu-latest
                      platform: linux
        
        runs-on: ${{ matrix.os }}
        
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            
            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: '20'
                  cache: 'npm'
            
            - name: Install dependencies
              run: npm ci
            
            - name: Build (macOS)
              if: matrix.platform == 'mac'
              env:
                  CSC_LINK: ${{ secrets.MAC_CERT_BASE64 }}
                  CSC_KEY_PASSWORD: ${{ secrets.MAC_CERT_PASSWORD }}
                  APPLE_ID: ${{ secrets.APPLE_ID }}
                  APPLE_ID_PASSWORD: ${{ secrets.APPLE_ID_PASSWORD }}
                  APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
              run: npm run build:mac
            
            - name: Build (Windows)
              if: matrix.platform == 'win'
              env:
                  WIN_CERT_PASSWORD: ${{ secrets.WIN_CERT_PASSWORD }}
              run: npm run build:win
            
            - name: Build (Linux)
              if: matrix.platform == 'linux'
              run: npm run build:linux
            
            - name: Upload artifacts
              uses: actions/upload-artifact@v4
              with:
                  name: ${{ matrix.platform }}
                  path: dist/
    
    release:
        needs: build
        runs-on: ubuntu-latest
        if: startsWith(github.ref, 'refs/tags/')
        
        steps:
            - name: Download all artifacts
              uses: actions/download-artifact@v4
              with:
                  path: dist/
            
            - name: Create Release
              uses: softprops/action-gh-release@v1
              with:
                  files: dist/**/*
              env:
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3.2 GitLab CI 配置 #

yaml

# .gitlab-ci.yml
stages:
    - build
    - release

build:mac:
    stage: build
    tags:
        - macos
    script:
        - npm ci
        - npm run build:mac
    artifacts:
        paths:
            - dist/
        expire_in: 1 week

build:windows:
    stage: build
    tags:
        - windows
    script:
        - npm ci
        - npm run build:win
    artifacts:
        paths:
            - dist/
        expire_in: 1 week

build:linux:
    stage: build
    tags:
        - linux
    script:
        - npm ci
        - npm run build:linux
    artifacts:
        paths:
            - dist/
        expire_in: 1 week

release:
    stage: release
    tags:
        - linux
    only:
        - tags
    script:
        - echo "Creating release..."
    artifacts:
        paths:
            - dist/

四、Docker 构建 #

4.1 Dockerfile #

dockerfile

# Dockerfile
FROM node:20

WORKDIR /app

RUN apt-get update && apt-get install -y \
    libsecret-1-dev \
    libgtk-3-0 \
    libnotify4 \
    libnss3 \
    libxss1 \
    libxtst6 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build:linux

CMD ["npm", "run", "build:linux"]

4.2 构建命令 #

bash

# 构建镜像
docker build -t electron-builder .

# 运行构建
docker run --rm -v $(pwd)/dist:/app/dist electron-builder

五、平台特定配置 #

5.1 macOS 配置 #

yaml

# electron-builder.yml
mac:
    category: public.app-category.productivity
    hardenedRuntime: true
    gatekeeperAssess: false
    entitlements: build/entitlements.mac.plist
    entitlementsInherit: build/entitlements.mac.plist
    darkModeSupport: true
    minimumSystemVersion: '10.15.0'

dmg:
    background: build/background.png
    iconSize: 100
    contents:
        - x: 380
          y: 180
          type: link
          path: /Applications
        - x: 130
          y: 180
          type: file

pkg:
    installLocation: /Applications
    background: build/background.png

5.2 Windows 配置 #

yaml

# electron-builder.yml
win:
    icon: build/icon.ico
    legalTrademarks: 'Copyright © 2024'
    requestedExecutionLevel: asInvoker

nsis:
    oneClick: false
    perMachine: false
    allowToChangeInstallationDirectory: true
    allowElevation: true
    installerIcon: build/icon.ico
    uninstallerIcon: build/icon.ico
    installerHeaderIcon: build/icon.ico
    createDesktopShortcut: true
    createStartMenuShortcut: true
    shortcutName: My App
    include: build/installer.nsh
    deleteAppDataOnUninstall: true
    displayLanguageSelector: true
    installerLanguages:
        - en_US
        - zh_CN
    language: '1033'

portable:
    artifactName: ${productName}-${version}-Portable.exe

5.3 Linux 配置 #

yaml

# electron-builder.yml
linux:
    category: Utility
    maintainer: your@email.com
    desktop:
        Name: My App
        Comment: My Electron App
        Categories: Utility;Development;
        StartupWMClass: my-app

AppImage:
    systemIntegration: ask

deb:
    priority: optional
    compression: xz
    depends:
        - libgtk-3-0
        - libnotify4
        - libnss3

rpm:
    compression: xz

snap:
    confinement: strict
    grade: stable
    plugs:
        - default
        - home
        - network

六、原生模块处理 #

6.1 重新编译原生模块 #

json

// package.json
{
    "scripts": {
        "postinstall": "electron-rebuild",
        "rebuild": "electron-rebuild -f -w native-module"
    }
}

6.2 预编译二进制 #

bash

# 为不同平台预编译
prebuild --all

# 上传到 GitHub Releases
prebuild --upload <token>

七、构建优化 #

7.1 并行构建 #

yaml

# GitHub Actions
jobs:
    build:
        strategy:
            matrix:
                os: [macos-latest, windows-latest, ubuntu-latest]
        runs-on: ${{ matrix.os }}

7.2 缓存依赖 #

yaml

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

- name: Cache electron
  uses: actions/cache@v4
  with:
      path: |
          ~/.cache/electron
          ~/.cache/electron-builder
      key: ${{ runner.os }}-electron-${{ hashFiles('**/package-lock.json') }}

7.3 减小体积 #

yaml

files:
    - electron/**/*
    - src/**/*
    - package.json
    - "!**/*.map"
    - "!**/*.ts"
    - "!**/node_modules/.bin"
    - "!**/node_modules/*/{test,tests,example,examples,doc,docs}"

八、常见问题 #

8.1 交叉编译问题 #

bash

# macOS 上构建 Windows 需要 Wine
brew install wine

# 或使用 Docker
docker run --rm -v $(pwd):/project electronuserland/builder:wine

8.2 原生模块问题 #

bash

# 确保原生模块为正确架构
electron-rebuild -f -w better-sqlite3 --arch=arm64

8.3 权限问题 #

bash

# Linux 上可能需要设置权限
chmod +x dist/my-app.AppImage

九、总结 #

9.1 核心要点 #

要点	说明
CI/CD	推荐使用 GitHub Actions
平台配置	针对各平台优化配置
原生模块	确保正确编译
缓存	加速构建过程
签名	各平台签名要求不同

9.2 下一步 #

现在你已经掌握了多平台构建，接下来让我们学习 React集成，深入了解 Electron 与 React 的集成开发！