跳到主要内容

应用打包

开发完成后，需要将 Electron 应用打包成可分发的格式。本节介绍如何使用 electron-builder 和 electron-forge 进行应用打包。

打包工具​

electron-builder​

electron-builder 是最流行的 Electron 打包工具，支持多平台打包。

electron-forge​

electron-forge 是官方推荐的打包工具，提供完整的开发工作流。

使用 electron-builder​

安装​

npm install electron-builder --save-dev

配置 package.json​

{
  "name": "my-app",
  "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": {
    "appId": "com.example.myapp",
    "productName": "我的应用",
    "directories": {
      "output": "dist"
    },
    "files": [
      "**/*",
      "!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
      "!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
      "!**/node_modules/*.d.ts",
      "!**/node_modules/.bin",
      "!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}",
      "!.editorconfig",
      "!**/._*",
      "!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}",
      "!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}",
      "!**/{appveyor.yml,.travis.yml,circle.yml}",
      "!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}"
    ],
    "win": {
      "target": "nsis",
      "icon": "build/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "build/icon.icns",
      "category": "public.app-category.utilities"
    },
    "linux": {
      "target": "AppImage",
      "icon": "build/icon.png",
      "category": "Utility"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true
    }
  },
  "devDependencies": {
    "electron": "^28.0.0",
    "electron-builder": "^24.9.1"
  }
}

打包命令​

# 打包当前平台
npm run build

# 打包 Windows
npm run build:win

# 打包 macOS
npm run build:mac

# 打包 Linux
npm run build:linux

# 打包所有平台
electron-builder -mwl

输出格式​

Windows：

  • nsis：安装程序
  • portable：便携版
  • zip：压缩包

macOS：

  • dmg：磁盘镜像
  • zip：压缩包
  • pkg：安装包

Linux：

  • AppImage：通用格式
  • deb：Debian/Ubuntu
  • rpm：Red Hat/Fedora
  • snap：Snap 包

使用 electron-forge​

安装​

npm install --save-dev @electron-forge/cli
npx electron-forge import

配置​

创建 forge.config.js：

module.exports = {
  packagerConfig: {
    asar: true,
    name: 'My App',
    executableName: 'my-app',
    icon: 'build/icon',
    appBundleId: 'com.example.myapp',
    appCategoryType: 'public.app-category.utilities',
    win32metadata: {
      CompanyName: 'My Company',
      OriginalFilename: 'My App'
    }
  },
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      config: {
        name: 'my-app',
        authors: 'My Company',
        description: '我的 Electron 应用'
      }
    },
    {
      name: '@electron-forge/maker-zip',
      platforms: ['darwin']
    },
    {
      name: '@electron-forge/maker-deb',
      config: {}
    },
    {
      name: '@electron-forge/maker-rpm',
      config: {}
    }
  ]
}

打包命令​

# 打包
npx electron-forge package

# 生成安装包
npx electron-forge make

ASAR 打包​

ASAR 是一种归档格式，可以将应用文件打包成单个文件。

启用 ASAR​

{
  "build": {
    "asar": true
  }
}

读取 ASAR 文件​

const fs = require('node:fs')
const path = require('node:path')

const filePath = path.join(__dirname, 'data.json')
const content = fs.readFileSync(filePath, 'utf-8')

ASAR 文件对 Node.js API 是透明的，可以像普通文件一样读取。

解压特定文件​

某些模块需要解压才能正常工作：

{
  "build": {
    "asar": true,
    "asarUnpack": [
      "**/*.node",
      "**/native-module/**"
    ]
  }
}

代码签名​

Windows 代码签名​

{
  "build": {
    "win": {
      "certificateFile": "cert.pfx",
      "certificatePassword": "password",
      "signingHashAlgorithms": ["sha256"],
      "sign": "./sign.js"
    }
  }
}

macOS 代码签名​

{
  "build": {
    "mac": {
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist"
    }
  }
}

自动更新​

配置自动更新​

const { autoUpdater } = require('electron')
const { dialog } = require('electron')

autoUpdater.setFeedURL({
  provider: 'github',
  owner: 'your-username',
  repo: 'your-repo'
})

autoUpdater.on('update-available', () => {
  dialog.showMessageBox({
    type: 'info',
    title: '更新可用',
    message: '发现新版本，正在下载...'
  })
})

autoUpdater.on('update-downloaded', () => {
  dialog.showMessageBox({
    type: 'info',
    title: '更新就绪',
    message: '新版本已下载，是否立即安装？',
    buttons: ['安装', '稍后']
  }).then(result => {
    if (result.response === 0) {
      autoUpdater.quitAndInstall()
    }
  })
})

app.on('ready', () => {
  autoUpdater.checkForUpdates()
})

配置 package.json​

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-username",
      "repo": "your-repo"
    }
  }
}

应用图标​

图标格式​

  • Windows：.ico 格式，建议 256x256
  • macOS：.icns 格式，建议 512x512
  • Linux：.png 格式，建议 512x512

图标位置​

build/
├── icon.ico      # Windows 图标
├── icon.icns     # macOS 图标
└── icon.png      # Linux 图标

生成图标​

使用 electron-icon-builder 自动生成各平台图标：

npm install electron-icon-builder --save-dev
npx electron-icon-builder --input=./logo.png --output=./build

打包优化​

减小体积​

  1. 排除不必要的文件
{
  "build": {
    "files": [
      "!**/*.map",
      "!**/*.ts",
      "!src/**"
    ]
  }
}
  1. 使用生产依赖
npm prune --production
  1. 压缩资源

压缩图片、CSS、JavaScript 文件。

打包配置示例​

{
  "build": {
    "appId": "com.example.myapp",
    "productName": "我的应用",
    "compression": "maximum",
    "files": [
      "**/*",
      "!**/node_modules/*/{CHANGELOG.md,README.md}",
      "!**/node_modules/.bin",
      "!src/**",
      "!**/*.map",
      "!**/*.ts"
    ],
    "extraResources": [
      {
        "from": "assets",
        "to": "assets"
      }
    ],
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64"]
        }
      ]
    },
    "mac": {
      "target": [
        {
          "target": "dmg",
          "arch": ["x64", "arm64"]
        }
      ]
    }
  }
}

跨平台打包​

在 macOS 上打包所有平台​

# 安装 Wine
brew install --cask wine-stable

# 打包 Windows
electron-builder --win

# 打包 Linux
electron-builder --linux

在 Windows 上打包​

Windows 上只能打包 Windows 和 Linux 版本：

electron-builder --win --linux

使用 CI/CD​

使用 GitHub Actions 自动打包：

name: Build

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: ${{ matrix.os }}
          path: dist/

常见问题​

打包后路径问题​

使用 app.getPath 获取正确的路径：

const { app } = require('electron')
const path = require('node:path')

const dataPath = path.join(app.getPath('userData'), 'data')

原生模块问题​

原生模块需要针对 Electron 重新编译：

npm install electron-rebuild --save-dev
npx electron-rebuild

杀毒软件误报​

Windows 上可能被杀毒软件误报，需要：

  1. 申请代码签名证书
  2. 向杀毒软件厂商提交白名单申请

总结​

Electron 应用打包需要注意：

  1. 选择合适的打包工具
  2. 配置正确的打包选项
  3. 处理应用图标和代码签名
  4. 考虑自动更新机制
  5. 优化打包体积
  6. 使用 CI/CD 自动化构建