MegSpot跨平台打包指南:electron-builder构建Windows/macOS/Linux安装包完整教程
MegSpot跨平台打包指南:electron-builder构建Windows/macOS/Linux安装包完整教程
MegSpot 是一款基于 Electron + Vue 2 构建的跨平台图片 & 视频对比应用。本教程将带你完整使用 electron-builder 打包 MegSpot 源码,一步步构建出 Windows、macOS、Linux 三大平台的安装包,新手也能一次构建成功。
一、环境准备:Node 16 + Yarn 装好依赖
MegSpot 通过 package.json 中的 volta 字段锁定了运行环境,建议保持一致,避免兼容性问题:
| 工具 | 推荐版本 | 说明 |
|---|---|---|
| Node.js | 16.20.2 | 构建脚本运行环境 |
| Yarn | 1.22.21 | 依赖管理(yarn.lock) |
| Electron | 22.x | package.json 指定 |
| electron-builder | 23.6.0 | 安装包构建核心工具 |
# 克隆源码
git clone https://gitcode.com/gh_mirrors/me/MegSpot
cd MegSpot
# 安装依赖(会自动执行 postinstall)
yarn
💡 yarn 安装完成后会自动触发 package.json 中的 postinstall 钩子执行 electron-builder install-app-deps,用于重建原生依赖,请勿跳过。
二、构建命令速查表:找到你的打包入口
所有打包命令都集中在 package.json 的 scripts 字段中,每个命令都是「清理 → 生产构建 → electron-builder 打包」的完整流水线:
| 命令 | 产物 | 适用场景 |
|---|---|---|
yarn dev |
开发窗口(端口 9080) | 日常开发、热更新调试 |
yarn build |
dist/electron 资源(无安装包) |
仅验证前端资源构建 |
yarn build:win32 |
Windows 32 位 .exe 安装包 |
Windows ia32 平台 |
yarn build:win64 |
Windows 64 位 .exe 安装包 |
Windows x64 平台(推荐) |
yarn build:mac |
macOS .dmg(x64 + arm64 双架构) |
仅在 macOS 上执行 |
yarn build:linux |
Linux .AppImage |
桌面 Linux 发行版 |
yarn build:dir |
未压缩的 *-unpacked 目录 |
快速验证打包结果 |
yarn build:all |
三大平台安装包一次全出 | 发版打包 |
其中生产构建由 .electron-vue/build.js 驱动,基于 webpack 将主进程与渲染进程分别打包到 dist/electron 目录,再由 electron-builder 接管生成最终安装包。
三、electron-builder 配置解析:读懂 build 字段
electron-builder 的全部配置内嵌在 package.json 的 build 字段中,关键项如下:
appId:应用唯一标识org.megvii.megspot(package.json),用于自动更新与系统识别;artifactName:产物命名规则${productName}-${version}-${os}-${arch}.${ext}(package.json),例如MegSpot-v2.2.10-win-x64.exe;directories.output:所有安装包统一输出到build目录(package.json);files:只打包dist/electron/**/*构建产物(package.json);extraResources:将 LICENSE、COPYRIGHT、CONTRIBUTOR_LICENSE_AGREEMENT.md 一并注入安装包;- 应用图标:macOS 使用 build/icons/logo.icns,Windows 使用 build/icons/logo.ico,修改图标后重新打包即可生效。
四、三大平台打包实操
Windows 打包:NSIS 图形化安装包
在 Windows 系统(或 CI)上执行:
yarn build:win64
对应 package.json 的 nsis 配置:oneClick: false 表示采用分步安装向导,allowToChangeInstallationDirectory: true 允许用户自定义安装目录。构建完成后在 build/ 目录即可看到 NSIS 安装向导 .exe。
macOS 打包:dmg 双架构
macOS 的 dmg 打包必须在 Mac 上执行:
yarn build:mac
package.json 中 mac.target 同时指定了 x64 与 arm64,因此一次构建可同时覆盖 Intel 与 Apple Silicon 机型;应用分类为 public.app-category.utilities,dmg 内部署图包含指向 /Applications 的快捷方式。
Linux 打包:AppImage 绿色免安装
yarn build:linux
package.json 指定 Linux 目标为 AppImage,单文件绿色版,下载即可运行,无需 root 权限。MegSpot 主进程入口 src/main/index.js 还内置了命令行参数解析,支持 ./MegSpot-x.x.x.AppImage [路径] [-i] [-v] [-h] 快捷进入图片/视频对比页面,非常适合 Linux 用户做命令行快捷启动。
五、查看产物与清理构建缓存
- 所有平台安装包都输出在根目录
build/下,命名遵循artifactName规则,方便按系统架构分发; - 反复构建前可执行 clearBuild.sh 清理
build/linux-unpacked、build/mac、build/win-unpacked中的历史产物,避免旧文件混淆; - 项目的历史 CI 配置可供参考:Windows 侧 appveyor.yml 使用 Visual Studio 2017 镜像执行
yarn build,macOS/Linux 侧 .travis.yml 通过矩阵同时构建双平台。
六、常见问题速查
| 问题 | 解决方案 |
|---|---|
| 下载 Electron 二进制过慢 | 为 yarn 配置 Electron 镜像源环境变量后重新安装 |
| 原生依赖报错 | 手动执行 electron-builder install-app-deps 重建依赖 |
| macOS 提示"不受信任的开发人员" | 未做代码签名所致,右键「打开」或通过系统设置放行 |
| 想发版并触发自动更新 | 执行 yarn publish:all(对应 package.json 的 publish 配置) |
结语
掌握本文的「环境准备 → 命令速查 → 配置解析 → 分平台实操」流程,你就能基于 electron-builder 独立构建出 MegSpot 三大平台的安装包。修改版本号(package.json 的 version 字段)后重新打包,即可发布你的专属定制版本 🎉
