OpenAlice 桌面应用图标管线解析:从社区原画到 macOS/Windows 多格式打包

原创2026-09-28 09:54:531,428 阅读

OpenAlice 桌面应用图标管线解析:从社区原画到 macOS/Windows 多格式打包

OpenAlice 桌面端是一款基于 Electron 的安装包外壳(@traderalice/desktop),其应用图标并非单一文件,而是一条"原始素材 → 统一成品 → 平台格式"的资产管线。本文以 apps/desktop/build/ICON_SOURCE.md 为核心骨架,结合仓库根目录的 electron-builder 配置、构建目录资产清单与桌面伴侣角色素材,完整梳理图标来源、1024px 圆角遮罩处理规格、icns/ico 两种平台格式的派生关系,以及替换素材时必须遵守的"三格式同步"纪律,为维护者提供可直接落地的图标维护与验证方案。

OpenAlice 桌面应用成品图标:1024×1024、圆角遮罩处理后的打包用图标

OpenAlice 图标原始社区原画:1254×1254、未做圆角遮罩处理的方形素材

一、图标来源:一份不改动角色的社区原画

icon-source.png 是图标管线的最上游素材。根据 ICON_SOURCE.md 的记录,它是"项目维护者于 2026-09-23 收到的未修改社区艺术作品"(unmodified community artwork supplied to the project maintainer)。

仓库中该文件的实际形态与文档描述一致:

属性 实际值
文件 icon-source.png
分辨率 1254 × 1254
处理状态 无圆角遮罩的方形原图
内容 OpenAlice 的 Alice 角色头像(浅金色头发、黑色兔耳发箍、椭圆眼睛与粉色腮红)

值得注意的是,ui/public/companion/alice.png 同样是 1254 × 1254 分辨率,且 docs/desktop-companion.md 明确记载桌面伴侣窗口"第一版使用维护者提供的角色形象"(a maintainer-supplied character)。由此可以推断:桌面伴侣窗口的角色素材与桌面应用图标共同源自同一份社区原画,图标管线强调"角色本身不重绘"(the character itself is not redrawn),正是为了在应用图标、伴侣窗口等不同载体之间保持角色形象的一致性。

二、成品处理规格:1024px 缩放与 210px 圆角透明遮罩

从原始素材到可打包的成品图标,ICON_SOURCE.md 规定了两个关键处理参数:

  1. 缩放到 1024 px:将 1254 × 1254 的原画等比缩小为 1024 × 1024 的方形底图,这是 macOS/Windows 现代图标规范通用的主尺寸;
  2. 210 px 圆角透明遮罩:在缩放后的图像上叠加四角圆角、四角外透明的遮罩,形成标准的桌面应用图标轮廓。

仓库实际产物验证了这两个参数——icon.png 为 1024 × 1024,四角呈明显圆角遮罩形态,角色细节(发色、发箍、五官、腮红)与 1254 × 1254 的原始素材完全一致,确认处理过程仅做缩放与遮罩、未重绘角色。

这一"缩放 + 遮罩"而非"重绘"的处理原则,保证了图标在任何屏幕密度下都忠实呈现原始艺术作品,也为后续格式派生提供了稳定、唯一的中间源。

三、三格式派生关系:icon.png → icon.icns / icon.ico

ICON_SOURCE.md 明确了格式派生的核心关系:

  • icon.png(1024px 成品)是所有平台格式的共同源;
  • icon.icns:供 macOS(DMG / ZIP 目标)使用;
  • icon.ico:供 Windows 使用,内部需包含 16–256 px 的多尺寸表示(with 16–256 px representations),以适配任务栏、窗口标题栏、开始菜单、资源管理器等不同显示场景。

仓库构建目录 apps/desktop/build/ 中三个打包格式文件齐备,与文档描述一一对应:

apps/desktop/build/
├── ICON_SOURCE.md                    # 本文依据:图标来源与处理规范说明
├── entitlements.mac.inherit.plist    # macOS 继承签名权利
├── entitlements.mac.plist            # macOS 主签名权利
├── icon-source.png                   # 原始社区原画(1254×1254,未处理)
├── icon.icns                         # macOS 打包用图标(由 icon.png 派生)
├── icon.ico                          # Windows 打包用图标(16–256px 多尺寸)
├── icon.png                          # 1024px 圆角遮罩成品,格式派生公共源
└── installer.nsh                     # Windows NSIS 安装器自定义脚本

四、electron-builder 集成:图标如何进入安装包

图标文件只有接入打包器配置才会真正生效。OpenAlice 的桌面打包由 electron-builder 驱动,其配置位于仓库根目录 package.json 的 build 字段(desktop 包的 pack 脚本以 --projectDir ../.. 指向仓库根,因此读取的是根配置):

  • 应用标识:appId: "com.traderalice.openalice",产品名 productName: "OpenAlice";
  • macOS 目标:dmg 与 zip,图标路径显式指向 icon.icns("icon": "apps/desktop/build/icon.icns"),并开启 hardenedRuntime、notarize(公证),签名权利文件即同一目录下的两份 entitlements plist;
  • Windows 目标:nsis,图标路径指向 icon.ico("icon": "apps/desktop/build/icon.ico"),安装器行为由 installer.nsh 自定义(包含更新时清理旧进程树与长路径目录的处理逻辑);
  • 打包后钩子:afterPack 指向 scripts/desktop-after-pack.mjs,配合根目录 electron:assert-package(scripts/assert-desktop-package.mjs)等脚本,共同构成安装包的打包与验收链路。

也就是说,只要 apps/desktop/build/ 目录下的 icon.png、icon.icns、icon.ico 三者同步更新,macOS 与 Windows 两个平台的安装产物会自动携带正确的应用图标,无需改动任何打包配置。

五、替换素材时的同步纪律

ICON_SOURCE.md 最后一条规定是整套管线的维护底线——替换艺术作品时,必须保持三种打包格式同步(Keep all three packaging formats in sync when replacing the artwork)。

对维护者而言,一次完整的图标替换应遵循以下步骤:

  1. 更新原始素材:用新的社区原画替换 icon-source.png,保留其"未修改原画"的身份,更新 ICON_SOURCE.md 中对应的接收日期与来源说明;
  2. 重新生成成品:将新原画等比缩放到 1024 px,并应用 210 px 圆角透明遮罩,覆盖 icon.png,确保角色不重绘;
  3. 再派生平台格式:由新的 icon.png 重新生成 icon.icns(macOS)与 icon.ico(Windows,16–256 px 多尺寸表示);
  4. 回归验证:通过根目录 package.json 中的 electron:pack、electron:assert-package、electron:smoke:packaged 等命令完成打包与冒烟验收,确认两个平台产物图标一致。

只要任何一步遗漏(例如只更新 icon.png 而忘记重新导出 icns/ico),就会在 macOS 或 Windows 上出现新旧图标不一致的发布事故,这正是文档将其列为强制纪律的原因。

六、从图标到桌面伴侣:同一角色的多载体呈现

图标管线的"不重绘"原则在 OpenAlice 桌面端还有一层延伸:ui/public/companion/ 下的伴侣窗口角色素材(alice.png,1254 × 1254)与图标原画同源同尺寸。桌面伴侣窗口由 apps/desktop/src/app-window.ts 创建,标题默认 OpenAlice,其交互细节(点击音效、气泡对话、窗口几何)详见 docs/desktop-companion.md。

因此在更换角色形象时,维护者不仅需要同步图标三格式,还应评估伴侣窗口素材是否需要同步更新,才能保证"应用图标、任务栏标识、桌面伴侣"三个呈现面使用同一代角色设计。

小结

OpenAlice 的桌面图标管理是一个边界清晰、纪律严格的资产管线:icon-source.png(社区原画)→ icon.png(1024px + 210px 圆角遮罩的公共成品)→ icon.icns / icon.ico(平台格式)。理解这条管线的关键在于三点:成品只做缩放与遮罩、不重绘角色;所有平台格式从 icon.png 单一派生;替换素材时必须三格式同步并走完 electron-builder 打包验收链路。以此为准,任何维护者都可以安全、一致地完成桌面端图标的迭代。

登录后查看全文
OpenAlice