一键打包跨平台:用 electron-builder 为 SightFlow 输出 Windows、macOS、Linux 安装包完整指南
一键打包跨平台:用 electron-builder 为 SightFlow 输出 Windows、macOS、Linux 安装包完整指南
SightFlow 桌面应用(sightflow-desktop-agent)是一个基于 Electron 的跨平台桌面 Agent 客户端,能看懂屏幕、执行操作并沉淀工作记忆。想把它交付给用户,就需要为 Windows、macOS、Linux 分别产出可安装的程序包。本文介绍如何借助 electron-builder 一键打包 SightFlow:从安装依赖、运行打包命令,到读懂 electron-builder.yml 配置,帮你快速产出 Windows 安装包、macOS 应用与 Linux 三大格式产物。
为什么选择 electron-builder 打包 SightFlow
SightFlow 由 Electron + electron-vite + React + TypeScript 构建(见 electron.vite.config.ts),electron-vite 负责把源码编译成可运行的 out/ 产物,而真正"把产物打成安装包"这一步交给 electron-builder 完成。二者分工如下:
| 工具 | 负责内容 |
|---|---|
| electron-vite | 编译主进程、preload、渲染进程,输出 out/ |
| electron-builder | 将 out/ 与资源打包为各平台安装包 |
也就是说,你平时用 npm run dev 开发的应用,最终通过 electron-builder 变成能双击安装的程序。下图就是打包后用户在 macOS 上会看到的设置窗口:
打包好的应用内置了独立的设置窗口,左侧为"基础配置"与"智能体"两个入口,用户可在其中填写视觉接口 Key、模型与 Provider 信息:
一键打包前的准备工作
打包前只需确认两件事:安装 Node.js(LTS)与 npm,然后执行依赖安装。SightFlow 的 package.json 中定义了 postinstall 脚本,安装依赖后会自动执行:
npm install
postinstall 会依次运行 patch-package(应用补丁)与 electron-builder install-app-deps(重建原生依赖),因此无需手动干预。
打包脚本一览
项目已在 package.json 预置好打包命令,全部"一条命令搞定":
| 脚本 | 等价命令 | 输出平台 |
|---|---|---|
npm run build:win |
npm run build && electron-builder --win |
Windows |
npm run build:mac |
electron-vite build && electron-builder --mac |
macOS |
npm run build:linux |
electron-vite build && electron-builder --linux |
Linux |
npm run build:unpack |
npm run build && electron-builder --dir |
不解包的目录(调试用) |
小技巧:先运行
npm run build:unpack可在本地"免安装"检查打包后的目录结构与asar内容,快速定位缺失文件问题。
三条命令打包三大平台
根据目标平台选择对应命令即可:
# Windows:产出 NSIS 安装程序
npm run build:win
# macOS:产出 .dmg 应用镜像
npm run build:mac
# Linux:产出 AppImage / snap / deb
npm run build:linux
执行完成后,安装包默认输出到项目根目录的 dist/ 文件夹。
跨系统构建注意事项:
- Windows 安装包:electron-builder 可跨系统产出 NSIS 安装程序,通常无需 Windows 环境。
- macOS 应用:签名与
.dmg制作依赖 macOS 工具链,建议在 macOS 上构建。 - Linux 产物:为获得最佳的
AppImage/snap/deb兼容性,建议在 Linux 环境构建。
读懂 electron-builder.yml 核心配置
所有打包行为都由 electron-builder.yml 声明,看懂它就等于掌握了打包细节:
| 配置项 | 作用 |
|---|---|
appId / productName |
应用标识 com.sightflow.desktop 与显示名 SightFlow |
directories.buildResources |
构建资源目录 build(图标、授权文件等) |
files |
打包时排除源码、配置文件等无关内容(L5-L11) |
asarUnpack |
将 resources/** 从 asar 中解出,保证运行时可访问(L12-L13) |
win.executableName |
Windows 可执行文件名 SightFlow |
nsis |
Windows 安装包行为(L16-L20) |
mac / dmg |
macOS 签名与镜像配置 |
linux.target |
Linux 输出格式 AppImage / snap / deb(L26-L30) |
npmRebuild: false |
跳过原生依赖重建,加速打包 |
关键细节解读:
nsis配置(electron-builder.yml):artifactName决定安装包名为${name}-${version}-setup.${ext}(如sightflow-desktop-agent-1.0.0-setup.exe);createDesktopShortcut: always表示安装后自动创建桌面快捷方式。asarUnpack(L12-L13):把resources/下的 Provider 等文件解包到app.asar.unpacked,保证运行时能按真实路径读取,避免打包后"文件不见了"的坑。mac配置(L21-L23):entitlementsInherit指向 build/entitlements.mac.plist(开启 JIT、允许未签名可执行内存等),notarize: false表示不做公证,适合自测分发。linux.target(L26-L30):同时产出AppImage(绿色免安装)、snap与deb三种格式,覆盖主流 Linux 发行版。
打包产物速览
一次完整打包后,dist/ 中会按平台生成对应产物:
| 平台 | 产物格式 | 默认命名 |
|---|---|---|
| Windows | NSIS 安装程序 | sightflow-desktop-agent-1.0.0-setup.exe |
| macOS | DMG 镜像 | sightflow-desktop-agent-1.0.0.dmg |
| Linux | AppImage / snap / deb | sightflow-desktop-agent-1.0.0.AppImage 等 |
命名规则由 artifactName 控制,其中 ${name}、${version}、${ext} 会被自动替换为 package.json 中的字段与文件扩展名。
常见打包问题排查
| 现象 | 可能原因与解决 |
|---|---|
| 打包后运行报"缺少文件" | 检查 files 排除项是否误伤;运行时读取的资源记得加入 asarUnpack |
| Linux 产物在某发行版打不开 | 在对应 Linux 环境重新 npm run build:linux,优先选 AppImage 分发 |
| macOS 应用无法安装 | 确认在 macOS 上构建;正式分发前需配置签名与公证 |
| 原生依赖报错 | 重新执行 npm install 触发 postinstall 重建依赖 |
小结
借助 electron-builder,SightFlow 的跨平台发布被简化为三条命令:build:win / build:mac / build:linux,配合一份 electron-builder.yml 即可同时产出 Windows 安装包、macOS 应用与 Linux 三大格式。理解 files、asarUnpack、nsis、linux.target 等关键配置后,你还能按需自定义图标、快捷方式与产物命名,轻松完成从源码到可分发安装包的完整流程。更多运行与配置说明,可参考 README.zh-CN.md。

