泡泡 IM

外观

打包 Windows / macOS 桌面客户端 ​

使用 Electron 源码模板，将已经部署好的泡泡 IM 网页打包为桌面软件。Windows 和 macOS 共用一份模板，本教程统一生成免安装版：用户解压后双击打开。

桌面窗口直接加载你配置的网页地址。网页更新后，重新加载即可使用最新页面；网页仍需保持在线。

只想体验桌面客户端时，可直接从泡泡 IM 下载页下载使用。下面的步骤适合需要更换应用名称、图标或网页地址的开发者。

准备 ​

  • Windows：Windows 10 / 11 64 位电脑，在 Windows 上生成 x64 单文件 EXE。
  • macOS：macOS 13.5 或更新版本，在 Mac 上生成应用 ZIP，满足本教程使用的 Node.js 24 LTS 的系统要求。
  • Node.js：安装 Node.js 24 LTS，保留安装程序中的 npm。安装后重新打开终端，执行 node -v、npm -v 确认命令可用。
  • Web 地址：先确认泡泡 IM 网页可以正常登录、聊天，并使用 HTTPS。

下载源码并修改配置 ​

下载 桌面客户端源码模板 v2.1.2，解压得到 popoim-desktop 文件夹。源码包已包含麦克风、摄像头所需的权限配置和授权处理，无需另行补文件。

打开 app.config.json，修改应用名称和网页地址：

json
{
  "name": "泡泡IM",
  "url": "https://live.popoim.com/im/",
  "appId": "com.popoim.desktop"
}
配置填写方式
name桌面应用名称，同时用于窗口标题和生成的文件名称。网页内的应用名称仍由管理后台设置。
url已部署 Web 客户端的完整 HTTPS 地址，保留实际路径，例如 https://你的域名/im/。
appId应用的固定标识。制作自己的品牌时改为自己的反向域名，例如 com.example.chat，以后升级保持不变。

更换图标时，用 1024 × 1024 的 PNG 替换 assets/icon.png，保留原文件名。只体验默认泡泡 IM 时，可以直接使用模板中的配置和图标。

Windows 打包 ​

打开命令提示符 ​

在文件资源管理器中打开解压后的 popoim-desktop 文件夹，确认能看到 package.json。点击地址栏，输入 cmd 并按回车，即可在当前文件夹打开命令提示符。

安装依赖并打包 ​

依次执行，上一条成功结束后再执行下一条：

sh
npm ci
npm run pack:win

首次执行会下载 Electron 和打包工具，请保持网络连接，等待命令结束。

运行与分发 ​

打开源码文件夹内的 release 目录，找到生成的 .exe，双击即可运行，无需安装。

发给用户时，只将这个 EXE 压缩为 ZIP：右键文件，选择「压缩为 ZIP 文件」（Windows 10 选择「发送到 → 压缩(zipped)文件夹」）。用户解压后只有一个 EXE，双击打开即可；不要直接在 ZIP 内运行。

窗口右上角提供 Windows 原生的最小化、最大化和关闭按钮，顶部标题栏可以拖动。关闭窗口会退出程序。

macOS 打包 ​

打开源码所在目录 ​

打开「终端」。如果源码解压在下载目录，执行：

sh
cd ~/Downloads/popoim-desktop

如果放在其他位置，在终端输入 cd ，把源码文件夹拖到终端补全路径，再按回车。确认当前文件夹内有 package.json。

安装依赖并打包 ​

sh
npm ci
npm run pack:mac

默认使用当前 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 的麦克风和摄像头能力，并处理两端的授权与拒绝提示。免安装不影响权限申请，但系统授权仍须由用户确认，不能在源码包中预先允许。

  • macOS：首次使用语音消息、通话或扫码时，按系统提示允许对应设备；语音不会额外申请摄像头。拒绝后，点击应用提示中的「打开系统设置」，在「隐私与安全性 → 麦克风 / 相机」重新允许，退出并重新打开应用。应用在发起设备权限申请后才会出现在对应列表，无需先安装。
  • Windows：设备访问被关闭时，应用会提供对应的系统设置入口。开启麦克风或相机访问，以及「允许桌面应用访问你的麦克风 / 相机」；桌面应用不一定有独立开关，无需为了出现在列表中另行安装。参见 Windows 摄像头、麦克风和隐私。

音视频通话沿用网页的 TRTC Web SDK 和后台通话配置。对外分发前，在实际设备上验证录音、摄像头和双端通话，确认设备、后台配置及网络可用。

正式分发 ​

模板已经处理外链、文件保存、登录状态保存、加载失败重试，以及通话中退出或重新加载的确认。本身不提供离线聊天和自动更新。

默认 Windows 未配置代码签名，macOS 使用 ad-hoc 签名且没有 Apple 公证，在其他电脑上可能受到系统安全拦截。向其他用户正式分发前，按照 Electron 签名说明配置自己的证书；macOS 还需启用公证。保留 electron-builder.config.cjs 中已有的权限配置，证书、密码和公证凭据不要放入源码 ZIP。ZIP 方便下载，不能替代签名、公证或用户授权。

安装依赖失败时，先检查能否访问 npm 和 Electron 的下载服务；如果提示找不到 package.json，先切换到解压后的源码目录。源码 ZIP 的 SHA-256 校验文件可用于核对下载文件是否完整。

打包效果 ​

macOS ​

macOS 原生客户端，展示群公告、有人提及和未读消息

Copyright © 泡泡 IM