一键打包跨平台:用 electron-builder 为 SightFlow 输出 Windows、macOS、Linux 安装包完整指南

原创2026-11-01 15:22:182,125 阅读

一键打包跨平台:用 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 上会看到的设置窗口:

SightFlow 桌面应用 electron-builder 打包产物的设置界面

打包好的应用内置了独立的设置窗口,左侧为"基础配置"与"智能体"两个入口,用户可在其中填写视觉接口 Key、模型与 Provider 信息:

SightFlow 应用打包后内置的智能体 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。

登录后查看全文
sightflow-desktop-agent