打包 Windows / macOS 桌面客户端 | 泡泡 IM 开发文档

使用 Electron 源码模板，将已经部署好的泡泡 IM 网页打包为桌面软件。Windows 和 macOS 共用一份模板，本教程统一生成免安装版：用户解压后双击打开。
桌面窗口直接加载你配置的网页地址。网页更新后，重新加载即可使用最新页面；网页仍需保持在线。
只想体验桌面客户端时，可直接从泡泡 IM 下载页下载使用。下面的步骤适合需要更换应用名称、图标或网页地址的开发者。
下载 桌面客户端源码模板 v2.1.2，解压得到 popoim-desktop 文件夹。源码包已包含麦克风、摄像头所需的权限配置和授权处理，无需另行补文件。
打开 app.config.json，修改应用名称和网页地址：
更换图标时，用 1024 × 1024 的 PNG 替换 assets/icon.png，保留原文件名。只体验默认泡泡 IM 时，可以直接使用模板中的配置和图标。
在文件资源管理器中打开解压后的 popoim-desktop 文件夹，确认能看到 package.json。点击地址栏，输入 cmd 并按回车，即可在当前文件夹打开命令提示符。
依次执行，上一条成功结束后再执行下一条：
首次执行会下载 Electron 和打包工具，请保持网络连接，等待命令结束。
打开源码文件夹内的 release 目录，找到生成的 .exe，双击即可运行，无需安装。
发给用户时，只将这个 EXE 压缩为 ZIP：右键文件，选择「压缩为 ZIP 文件」（Windows 10 选择「发送到 → 压缩(zipped)文件夹」）。用户解压后只有一个 EXE，双击打开即可；不要直接在 ZIP 内运行。
窗口右上角提供 Windows 原生的最小化、最大化和关闭按钮，顶部标题栏可以拖动。关闭窗口会退出程序。
打开「终端」。如果源码解压在下载目录，执行：
如果放在其他位置，在终端输入 cd ，把源码文件夹拖到终端补全路径，再按回车。确认当前文件夹内有 package.json。
默认使用当前 Node.js 的架构：Apple Silicon 电脑建议安装 ARM64 版 Node.js，Intel Mac 安装 x64 版 Node.js。产物名称中的 arm64、x64 会标明架构。
打开源码文件夹内的 release 目录，将生成的 .zip 发给相同架构的 Mac 用户。用户双击 ZIP 解压，得到 泡泡IM.app（或自定义的应用名称），再双击打开，无需安装或拖入「应用程序」。
左上角使用 macOS 系统红黄绿按钮，顶部标题栏可以拖动。关闭窗口后应用保留运行，点击 Dock 图标恢复；从应用菜单选择「退出」或按 ⌘Q 完全退出。
依赖已经安装时，修改名称、网址或图标后，只需重新执行对应平台的打包命令。升级版本时修改 package.json 中的 version，例如从 2.1.2 改为 2.1.3。
需要先预览窗口时，可在源码目录执行 npm start；关闭预览后再打包。
模板已配置 macOS 的设备用途声明、主应用及 Helper 的麦克风和摄像头能力，并处理两端的授权与拒绝提示。免安装不影响权限申请，但系统授权仍须由用户确认，不能在源码包中预先允许。
音视频通话沿用网页的媒体能力与自建通话服务配置，无需额外接入第三方云通话 SDK。对外分发前，在实际设备上验证录音、摄像头和双端通话，确认设备、后台配置及网络可用。
模板已经处理外链、文件保存、登录状态保存、加载失败重试，以及通话中退出或重新加载的确认。本身不提供离线聊天和自动更新。
默认 Windows 未配置代码签名，macOS 使用 ad-hoc 签名且没有 Apple 公证，在其他电脑上可能受到系统安全拦截。向其他用户正式分发前，按照 Electron 签名说明配置自己的证书；macOS 还需启用公证。保留 electron-builder.config.cjs 中已有的权限配置，证书、密码和公证凭据不要放入源码 ZIP。ZIP 方便下载，不能替代签名、公证或用户授权。
本模板使用 electron-builder 26，以下参数按该版本说明。购买的完整 Web 源码包中，桌面工程在 app-web/desktop/；下面的命令在包含桌面 package.json 的目录执行。
需要自己的 Windows 代码签名证书或签名服务。它与 Android 的签名文件、网站 HTTPS 证书不同，不能互相代替。
如果证书提供可用的 .pfx / .p12 文件，在本目录的 PowerShell 中设置本次打包使用的证书，然后打包：
路径和密码换成自己的，不要把示例当作真实配置。如果使用 USB 硬件证书或云签名服务，请按证书提供方和 electron-builder 26 的 Windows 签名说明 配置对应方式。
为避免忘记配置证书时仍生成未签名的发布包，可以在 electron-builder.config.cjs 的 module.exports 最外层增加 forceCodeSigning: true。打包后，在 Windows 文件属性的「数字签名」中检查发布者是否为自己。签名并不保证新软件立即消除所有系统信誉提示。
签名说明软件来自谁；公证是 Apple 对分发包的检查。面向其他用户分发时，需要用自己的 Apple 开发者账号完成这两项。
App 专用密码在 Apple 账号的登录与安全设置中生成，不是直接填写日常登录密码。以上信息只在自己的电脑或安全的构建环境中填写，不要随源码、聊天记录或安装包发给别人。
详细参数见 electron-builder 26 的 macOS 签名说明 和 公证配置。这里生成的是直接分发版本，提交 Mac App Store 还需要另外的商店配置。
安装依赖失败时，先检查能否访问 npm 和 Electron 的下载服务；如果提示找不到 package.json，先切换到解压后的源码目录。源码 ZIP 的 SHA-256 校验文件可用于核对下载文件是否完整。