B
ByteNote

Electron 跨平台打包笔记

25 min read

Electron 支持在一个平台上为其他平台构建应用程序，这称为跨平台构建。

在 macOS 上打包 Windows 应用

方法一：electron-builder（推荐）

安装

npm install --save-dev electron-builder

配置 package.json

{
  "name": "my-electron-app",
  "scripts": {
    "build:win": "electron-builder --win",
    "build:mac": "electron-builder --mac",
    "build:linux": "electron-builder --linux"
  },
  "build": {
    "appId": "com.example.myapp",
    "productName": "My Electron App",
    "directories": {
      "output": "dist"
    },
    "win": {
      "target": [
        {
          "target": "nsis",
          "arch": ["x64", "ia32"]
        }
      ],
      "icon": "assets/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns"
    },
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png"
    }
  }
}

构建命令

# 构建 Windows 版本
npm run build:win

# 构建所有平台
npx electron-builder --win --mac --linux

方法二：electron-packager

安装

npm install --save-dev electron-packager

使用命令

# 基本用法
npx electron-packager . myapp --platform=win32 --arch=x64 --out=dist/

# 详细参数
npx electron-packager . myapp \
  --platform=win32 \
  --arch=x64 \
  --electron-version=latest \
  --out=dist/ \
  --icon=assets/icon.ico \
  --overwrite

方法三：electron-forge

安装和初始化

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

配置 forge.config.js

module.exports = {
  packagerConfig: {
    icon: './assets/icon'
  },
  makers: [
    {
      name: '@electron-forge/maker-squirrel',
      config: {
        name: 'my_electron_app'
      }
    },
    {
      name: '@electron-forge/maker-zip',
      platforms: ['darwin']
    },
    {
      name: '@electron-forge/maker-deb',
      config: {}
    }
  ]
};

构建命令

npm run make -- --platform=win32

重要注意事项

1. 代码签名限制

  • ❌ 无法在 macOS 上对 Windows 应用进行代码签名

  • ✅ 需要在对应平台上进行代码签名

  • 🔧 可以使用 GitHub Actions 等 CI/CD 工具实现自动签名

2. 原生依赖处理

# 重新构建原生模块
npm rebuild --arch=x64
npx electron-rebuild --arch=x64

3. 图标要求

  • Windows: .ico 格式，推荐 256x256 像素

  • macOS: .icns 格式，包含多种尺寸

  • Linux: .png 格式，推荐 512x512 像素

4. 测试策略

  • 使用虚拟机测试 Windows 版本

  • 利用云服务（如 BrowserStack）进行跨平台测试

  • 设置 CI/CD 自动构建和测试

最佳实践

1. 统一构建脚本

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

2. 环境配置

# 设置 npm 镜像加速构建
npm config set target_platform win32
npm config set cache /tmp/.npm

3. 文件结构

project/
├── src/
├── assets/
│   ├── icon.ico     # Windows 图标
│   ├── icon.icns    # macOS 图标
│   └── icon.png     # Linux 图标
├── dist/            # 构建输出
├── package.json
└── forge.config.js  # 或其他配置文件

常见问题解决

Q: 构建失败提示缺少依赖？

# 清理缓存重新安装
rm -rf node_modules package-lock.json
npm install

Q: 原生模块兼容性问题？

# 使用 electron-rebuild
npx electron-rebuild

Q: 构建包过大？

  • 使用 .gitignore 和 files 字段排除不必要文件

  • 启用 asar 压缩

  • 移除开发依赖

相关资源

创建时间：2025年7月9日
适用版本：Electron 25+