企业官网建设流程全解析

ente Ensu iOS 应用图标更新指南：从 1024×1024 透明前景图到 Any / Dark / Tinted 三变体的完整流程

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

Ensu 是 ente 生态中的 iOS 应用（源码位于 apple/apps/ensu，其中 README.md 记录了其基于 Rust 的端侧模型推理构建方式）。本文以仓库文档 apple/apps/ensu/docs/app-icon.md 为核心骨架，结合 AppIcon.appiconset 资产目录的真实结构与源码，系统讲解 Ensu iOS 应用图标从源图准备、三变体导出到资产目录落地的完整更新流程。读完本文，你将掌握 iOS 图标 Any / Dark / Tinted 三种外观变体的生成规格、背景色取值原理，以及如何在 Xcode 中重建应用验证图标生效。

背景：为什么一颗 iOS 图标要准备三份变体

从 iOS 13 开始，系统会根据用户当前的外观模式（浅色 / 深色 / 强调色）对应用图标进行动态适配，Apple 通过资产目录（Asset Catalog）的appearances声明支持三种外观变体：

ente 仓库中 Ensu 的 AppIcon.appiconset/Contents.json 正是按这一模型组织的：IconOGAny.png不带appearances声明（默认外观），IconOGDark.png声明了luminosity / dark，IconOGTinted.png声明了luminosity / tinted。

Ensu 采用的设计策略是：只用一份 1024×1024 的透明前景图（前景居中、画布为正方形），在此基础上叠加不同的背景色导出三份变体，而不是为每个变体单独绘制整套图标。这样既保证了三份素材在图形上完全一致（视觉上仅背景不同），又让深色模式和着色模式下系统能自行叠加各自的背景与染色效果。

源图规范：1024×1024 透明前景

更新图标的第一步是准备源图。文档明确规定源图必须满足以下三点：

1. 透明背景：前景图形必须放在透明背景上，背景不能有任何颜色或杂边，否则叠加背景色时会污染最终图标；
2. 1024×1024 画布：前景必须居中放在一块 1024×1024 的正方形画布上，这是 iOS 单尺寸通用图标（single size universal icon）的标准规格；
3. 不留内边距：如果源图尺寸不是 1024×1024，应先把源图整体缩放（rescale）到 1024×1024，而不是通过加 padding 撑大画布——加 padding 会让前景在后续圆角裁剪和缩略展示时显得偏小。

从源码结构看，Ensu 的前景素材在 EnsuLogoForeground.imageset 中存放了一份 432×432 的EnsuLogoForeground.png（白色 "ensu" 字标风格的透明前景），可以推断它是图标前景图形的候选来源之一——若以它为基础制作 1024×1024 图标，就需要按上述规则放大到目标画布。

三变体导出规格

源图就绪后，需要导出以下三份 1024×1024 变体：

三份文件同为 1024×1024 PNG，替换时只需覆盖同名文件即可（当前仓库中三个文件均为 1024×1024 尺寸，符合规格）。

资产目录落地：AppIcon.appiconset 结构与 Contents.json

三份变体导出后，需要放到资产目录：

apple/apps/ensu/Ensu/Assets.xcassets/AppIcon.appiconset/ ├── Contents.json ├── IconOGAny.png ├── IconOGDark.png └── IconOGTinted.png

其中Contents.json是资产目录的描述文件，Xcode 依据它把文件名与外观声明绑定起来。Ensu 当前的 Contents.json 内容如下：

{ "images" : [ { "filename" : "IconOGAny.png", "idiom" : "universal", "platform" : "ios", "size" : "1024x1024" }, { "appearances" : [ { "appearance" : "luminosity", "value" : "dark" } ], "filename" : "IconOGDark.png", "idiom" : "universal", "platform" : "ios", "size" : "1024x1024" }, { "appearances" : [ { "appearance" : "luminosity", "value" : "tinted" } ], "filename" : "IconOGTinted.png", "idiom" : "universal", "platform" : "ios", "size" : "1024x1024" } ], "info" : { "author" : "xcode", "version" : 1 } }

关键字段说明：

• idiom: "universal"+platform: "ios"+size: "1024x1024"：声明这是适用于所有 iOS 设备的单尺寸通用图标；
• appearances：可选字段，luminosity / dark表示深色变体，luminosity / tinted表示着色变体；不写该字段即默认的 Any 变体；
• 文件名必须与磁盘上的实际文件一一对应，若导出时改了文件名，需要同步修改这里的filename字段。

需要留意的是：替换图标时只动 AppIcon.appiconset 即可，同目录下的 AppIconMac.appiconset 是 macOS 平台的图标集合（含 16×16 到 512×512@2x 共 10 个规格），与 iOS 图标流程相互独立，除非同时维护 macOS 端，否则无需改动。

五步操作流程

综合 app-icon.md 的步骤，完整更新流程如下：

1. 打开透明源 PNG：确保源图是带透明通道的 PNG（非 JPG，JPG 无法保存透明信息）。
2. 居中与缩放：确认前景在 1024×1024 画布上居中；若源图尺寸不同，先整体缩放（rescale）到 1024×1024，不要通过添加 padding 来凑尺寸。
3. 导出三份变体：
   • IconOGAny.png：叠加#FFEEDD背景；
   • IconOGDark.png：保持透明背景（让系统深色渐变透出）；
   • IconOGTinted.png：叠加白色背景（保证着色行为正确）。
4. 替换资产目录文件：将三份 PNG 覆盖写入 Ensu/Assets.xcassets/AppIcon.appiconset/，保持文件名不变（若变更文件名需同步更新 Contents.json 的filename字段）。
5. 在 Xcode 中重建应用：重新编译使资产目录刷新，新图标才会被打进产物。

重建与验证

文档强调第 5 步必须**重建（rebuild）**应用，因为资产目录（Asset Catalog）在编译期被压缩进 App 包，仅刷新模拟器或切换前台不会重新生成图标。重建有两种方式：

• Xcode 图形界面：打开 Ensu.xcodeproj，选择Ensuscheme，Build & Run；
• 命令行（终端构建）：参照 apple/apps/ensu/README.md 的 Terminal builds 一节，例如在模拟器上构建安装：

cd apple/apps/ensu xcodebuild -scheme Ensu -destination 'platform=iOS Simulator,name=iPhone 17' xcrun simctl install booted \ ~/Library/Developer/Xcode/DerivedData/Ensu-*/Build/Products/Debug-iphonesimulator/Ensu.app xcrun simctl launch booted io.ente.ensu

验证要点：

• 浅色模式下主屏幕图标应显示 Any 变体（米白底）；
• 系统切换为深色模式后，图标应变为 Dark 变体（透明底叠加系统深色渐变）；
• 桌面图标着色生效的场景下应表现为 Tinted 变体（白底染色）；
• 若图标仍显示旧图，先确认资产目录文件已被覆盖，再执行一次 Clean（xcodebuild clean）后重新构建，以排除编译缓存。

注意事项与常见问题

1. 背景色必须严格按规格：Dark 变体若误填了不透明背景，深色模式下系统渐变无法透出，图标会显得是"贴上去的一块"；Tinted 变体若不用白底，着色算法计算出的前景对比度可能异常。
2. 画布尺寸与内边距：前景未满 1024×1024 或留有大量 padding，会导致最终图标在系统圆角裁切、主屏幕缩略展示时视觉占比偏小。
3. 文件名一致性：Assets 目录下 PNG 文件名与 Contents.json 的filename必须完全一致（含大小写），否则构建时报 "None of the input catalogs contained a matching app icon" 类错误或直接使用占位图标。
4. 缓存问题：模拟器或真机偶发不刷新图标，卸载 App 重装、或在 Xcode 中 Product → Clean Build Folder 后再构建即可。
5. 只改 iOS 图标：若此次仅更新 iOS 图标，无需触碰 AppIconMac.appiconset，避免扩大改动面。

小结

Ensu 的图标更新策略可以概括为一句口诀：一份 1024×1024 透明前景居中源图，导出 Any（#FFEEDD 底）、Dark（透明底）、Tinted（白底）三份变体，同名覆盖到 AppIcon.appiconset，重建即生效。这一流程同样适用于 ente 仓库中其他 iOS 应用（如 apple/apps/cast）的图标维护，只需将上述规格套用到对应应用的 Assets.xcassets 即可。

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente