桌面安装包构建

生成 Linux / Windows 安装包。日常开发只需 npm run build（出 web 产物），本文只讲分发用安装包。

命令

npm run build:linux     # AppImage + deb
npm run build:win       # NSIS 安装器

产物在 release/（已在 .gitignore 里，不要提交 —— AppImage 约 122MB、deb 约 100MB）。

⚠️ 安装包里嵌的是前端的一份快照（构建时的 dist/）。因此任何前端改动（组件、样式、主题、背景）之后都必须重打安装包，否则 release/ 里那份会静默地是旧界面 —— 而它本身不会报错，只有装上去的人会看到与 Web 不一致的样子。

自查（不需要真正安装）：直接查包内 asar 里的 CSS 有没有你刚加的东西：
node -e "const a=require('@electron/asar');const l=a.listPackage('release/linux-unpacked/resources/app.asar');
const c=l.find(p=>/\\/dist\\/assets\\/index-.*\\.css$/.test(p));
console.log(c, a.extractFile('release/linux-unpacked/resources/app.asar', c.replace(/^\\//,'')).toString().includes('--bg-scrim'))"

本机环境的两个坑

1. `SHASUMS256.txt` 不可达 → 构建会卡 10 分钟后失败

现象：

• downloaded      label=electron progress=100%
⨯ Timeout awaiting 'request' for 600000ms  failedTask=build

不是构件下载失败。实测该网络下：

URL	结果
`…/releases/download/v44.2.0/electron-v44.2.0-linux-x64.zip`	HTTP 206，0.8s ✅
`…/releases/download/v44.2.0/SHASUMS256.txt`	直连 20s 超时、走 Clash 代理也失败 ❌

@electron/get 即使命中本地缓存，也会去取 SHASUMS256.txt 校验，于是卡死。

绕过（命令行覆盖，不要写进 package.json）：

npx electron-builder --linux -c.electronDownload.isVerifyChecksum=false

为什么不写进配置：那会让今后每一次构建都跳过完整性校验。一次性绕过网络限制不该固化成永久弱化的默认值。关校验后，被篡改的镜像可以在 TLS 之外替换构件而无人察觉 —— 本场景可接受（构件来自官方 GitHub 的 TLS 连接，且本地缓存已验证可读），但不该成为默认。

2. 依赖缓存齐全，可离线完成

~/.cache/electron-builder/ 下以下条目的 .state 均为 complete 即可离线：

appimage-12.0.1（AppImage 运行时）、fpm@2.1.4（deb）、7zip@1.0.0、 nsis-resources-3.4.1 + nsis-3.0.4.1（Windows 安装器）。

Electron 二进制在 ~/.cache/electron/（首次需要网络，electron-v44.2.0-linux-x64.zip 约 123MB）。

package.json 里与打包有关的元数据

这些字段缺失会让某个 target 直接失败，报错信息不一定指向字段本身：

字段	位置	不填的后果
`description`	根	deb 描述为空
`author`（含 email）	根	deb 缺 maintainer 信息
`homepage`	根	deb 直接构建失败：`Please specify project homepage`
`desktopName`	根	窗口无法与 `.desktop` 关联（`StartupWMClass` 缺失）
`linux.syncDesktopName`	`build.linux`	同上，配合 `desktopName` 一起用
`linux.synopsis`	`build.linux`	deb 描述只有一行

⚠️ 当前 author.email 是容器占位值 jianf@noreply.localhost， homepage 是内网 Gitea 地址。正式对外分发前必须替换成真实值。

两个产物的实质区别（实测）

	AppImage	deb
`.desktop` 的 Exec	`AppRun --no-sandbox %U`	`/opt/AgentMail/agentmail-web %U`
Chromium 沙箱	禁用 —— squashfs 里无法保留 setuid 的 `chrome-sandbox`	启用 —— postinst 按能力决定：能跑用户命名空间则 `0755`，否则设 `4755`；并安装 AppArmor 配置（Ubuntu 24+ 需要）
卸载	删文件即可	postrm 清理 alternatives、AppArmor 配置、desktop/mime 数据库

要给用户装，优先分发 deb：沙箱可用、依赖声明完整、可被包管理器卸载。

验证产物的方法（别只看文件存在）

# deb 元数据与依赖
dpkg-deb --info release/*.deb
# deb 内容布局（含 chrome-sandbox 权限、desktop 文件、图标尺寸）
dpkg-deb --contents release/*.deb | grep -E '\.desktop|chrome-sandbox|app\.asar'
# postinst 的沙箱策略
dpkg-deb --control release/*.deb /tmp/ctl && cat /tmp/ctl/postinst

# AppImage：不依赖 FUSE 解包并看载荷
./release/AgentMail-0.1.0.AppImage --appimage-extract
ls squashfs-root/resources/app.asar
# 确认 asar 里是真正构建的应用（而不是空壳）
node -e "const a=require('@electron/asar');console.log(a.listPackage('release/linux-unpacked/resources/app.asar').filter(p=>/^\/(dist|electron)\//.test(p)).join('\n'))"

4.7 KiB Raw Blame History Unescape Escape