随着 macOS 26 Tahoe 引入全新的 Liquid Glass 视觉语言,应用图标的呈现机制也发生了显著变化。对于许多独立开发者和使用 Qt、C++ 等非 Xcode 工具链开发的团队来说,如何让应用在 Default、Dark、Clear(Light/Dark)和 Tinted 等图标样式下都能正确显示,成为一项必须面对的工程任务。本文将从格式、工具、构建流程到调试与兼容性策略,全面讲解将老图标迁移到 macOS 26 的实用方法与注意事项,帮助你在不影响早期系统支持的前提下适配新系统的视觉要求。 首先要理解的新格式与概念是 .icon 与 Assets.car。macOS 26 开始支持一种新的应用图标格式,扩展名为 .icon。与以往单文件的 .icns 不同,.icon 是一个包含多种资源的文件夹(在 Finder 中通常隐藏扩展名,看起来像单个文件),内部可包含多组资源,类似图层。
Apple 官方提供的工具 Apple Icon Composer 可以用于生成 .icon,但市场上也有设计师和自由职业者可以基于矢量稿转换并优化不同图标变体。需要注意的是,.icon 文件内部应尽量只包含最多四个组(group),超过这个数量可能导致 actool 在编译时代码生成或资源合并失败。 生成 Assets.car 是第二步。macOS 使用资产目录(asset catalog)来管理应用图标和其他图像资源,actool 是将 .icon 转换为 Assets.car(一个二进制资源包)的官方工具。典型的生成命令需要在 macOS 26、Xcode 26 与 macOS 26 SDK 环境下运行,例如使用 xcrun actool 指定 --compile 输出目录、应用图标名、目标设备与最低部署版本。生成时要注意将 --minimum-deployment-target 设置为 26.0(如果目标只需 macOS 26),并使用 --include-all-app-icons 等选项确保所有变体被包含。
生成过程中 actool 会输出一个 temp.plist,但在实践中这个 plist 有时并不会按预期包含可直接引用的图标映射信息,因此不要完全依赖它作为唯一参考。 生成好的 Assets.car 可以用 assetutil 检查其内容。使用 xcrun --sdk macosx assetutil --info Assets.car 可以导出一个 JSON 格式的内容清单,这个清单非常有用:它显示了资源的名字、可用变体与兼容性信息,帮助你确定在 Info.plist 中应该引用的图标名称或确认哪些资源实际被打包进了 Assets.car。通过分析 assetutil 的输出,你还能判断某些图标变体是否被正确命名为应用图标集中使用的键名。 在 Info.plist 中引用新图标的关键字段是 CFBundleIconName。将以下键值对加入到你的 Info.plist(与 CFBundleGetInfoString 同级)即可让系统查找资产目录中的应用图标: <key>CFBundleIconName</key> <string>application</string> 上面字符串的命名通常基于 .icon 文件的文件名(file stem),但实际行为以 assetutil 导出的 JSON 为准:查找你在 Assets.car 中的 app icon 名称并在 plist 中填写相应值。
务必确保名称精确匹配,否则系统可能回退到旧的 .icns 或显示占位符。 为兼容旧系统,建议同时保留原有的 .icns 文件并将其与新的 Assets.car 一并放在应用的 Resources 目录中,但务必在对应用签名之前完成这一步。将两者都放入资源包可以保证在 macOS 26 以外的系统(例如 macOS 12、15 等)仍能显示正确图标,同时也能让某些早期系统在有条件时优先使用 Assets.car。实践中有报道指出,某些较早版本的 macOS(例如 macOS 12、15)有时也会优先读取资产目录中的图标,因此同时保留两种格式有利于最大兼容性。 如果你使用 Xcode 开发,许多步骤会被 IDE 自动处理:资源目录、资产目录的创建与打包通常由 Xcode 在构建阶段完成。但对于使用 Qt Creator、CMake 或其他工具链的开发者,你需要手工运行 actool 生成 Assets.car,然后在构建脚本中将其复制进 .app 的 Resources 文件夹。
需要特别注意的是,某些自动化签名或打包步骤可能在签名之后修改包内容,务必在签名前完成 Assets.car 与 .icns 的拷贝,并在签名之后验证签名完整性。 设计层面的要求也不可忽视。Liquid Glass 对图标的处理包括模糊、半透明、背景虚化和颜色叠加等效果,这意味着原始图标需要为不同的外观风格准备合适的素材或在设计时考虑"留白"与透明度。通常需要为 Default、Dark、Clear/Light、Clear/Dark 与 Tinted 五种 Icon & widget style 提供不同的视觉变体,以避免系统对图标自动添加灰色背景或不合适的色调。建议从矢量源文件开始制作不同图层与变体,设计时留出安全边距并测试在不同透明度与背景模糊下的可读性。若不想自己设计,可以聘请熟悉 macOS 新规范的设计师或在 Fiverr、Upwork 等平台寻找经验丰富的自由职业者来转换矢量稿,并确保 .icon 中的组数量不超过四个以避免编译问题。
实际操作中可能遇到的常见问题包括:Finder 隐藏 .icon 扩展名导致误解、assetutil 输出与期望不符、actool 报错因为 .icon 内组过多、Info.plist 中 CFBundleIconName 配置错误或拼写不一致、以及在某些旧系统上预期的回退机制没有生效。遇到错误时,第一步是使用 assetutil 检查 Assets.car 的内容,确认图标名称与你的 Info.plist 配置一致。第二步是在构建机器上确保使用的是 macOS 26 与 Xcode 26 的 SDK 来运行 actool,如果在旧系统上尝试生成 Assets.car 很可能失败或产生不兼容的二进制格式。 另一个需要注意的点是测试覆盖。将应用在多台装有不同 macOS 版本的机器上测试是非常必要的。不同的 Icon & widget style 设置可能会对图标做出不同处理,尤其是 Clear(Light/Dark)和 Tinted 模式会对颜色与透明度有比较激进的调整。
实际测试时应分别切换系统偏好设置中的 Appearance > Icon & widget style 到每一种样式,观察 Dock、Finder、Launchpad、应用切换器等不同场景下的显示效果。录制截图或建立一个小型的视觉回归测试集可以在后续的更新中确保外观一致性。 构建流程的自动化建议可以大大减少重复劳动。将 actool 与 assetutil 的运行封装到 CMake 脚本或构建脚本中,确保在构建流程开始阶段就生成并校验 Assets.car,然后在打包阶段将其复制到 .app 的 Resources。构建脚本中加入对 assetutil 输出的解析,如果找不到指定的 app icon 名称就中断构建并报错,能够及早捕获配置不一致的问题。此外,建议将设计源文件(如 SVG、PDF 或 AI)与 .icon 源文件一起纳入版本控制,便于回溯与协作。
最后提供一些实践层面的建议与最佳做法:始终保留旧的 .icns 以便兼容旧系统并作为后备;在签名前完成 Assets.car 与资源的放置,并在签名后验证完整性;与设计师沟通时明确要为 Liquid Glass 的五种风格提供视觉验证样例;在生成 .icon 时控制组数以避免 actool 编译问题;使用 assetutil 导出的 JSON 作为检查点,确保 Info.plist 中的 CFBundleIconName 与资产目录中的 app icon 名称一致;并在多台不同 macOS 版本机器上进行视觉回归测试。 适配 macOS 26 Tahoe 的图标确实会带来一些额外工作,但一次性按规范构建好资产目录并加入到常规构建流程中,就能在未来的系统更新中减少重复劳动。通过结合设计上的预先规划、自动化构建脚本与多版本测试,你可以既保证在最新系统中提供良好的视觉体验,又不放弃对旧版本的兼容性。希望这些步骤与建议能让你更快完成迁移并减少调试时间,避免在应用上看到被系统处理后产生的灰色背景或不合适的色调。祝你图标适配顺利,发布无忧。 。
