Icon Composer 图标怎么接入 Xcode 27？2026 验收清单

Icon Composer 接入失败，常见原因不是“文件没有导入”，而是把设计源文件、构建资源和营销素材混成了同一个概念。

Apple 的接入文档说明，Icon Composer 可以用多层文件表示不同平台和外观；将 .icon 文件加入 Xcode 后，它可能替代原先用于表示 App 图标的资产目录。如果旧系统必须继续显示原始图标，应保留传统资产目录并单独验证。

你需要特别防范 3 个限制：

1. 文件进入 Project navigator，不代表进入构建。
   Target Membership 未勾选时，本地可以打开文件，但 Archive 可能完全不包含它。

2. 文件名与 Target 设置必须对应。
   Target 中的 App Icon 名称应匹配 .icon 文件名，通常不包含扩展名。项目存在多个图标文件时，名称错误会导致构建继续读取其他资源。

3. 预览、设备图标和商店素材属于不同验收层。
   Icon Composer 画布只证明编辑器能够渲染。设备桌面读取安装包资源，TestFlight 和 App Store Connect 还涉及构建处理及发布关联。

分层素材准备

优先从分层 SVG 开始。文字应转换为轮廓，避免远程构建节点缺少对应字体。若使用 PNG，应确认图片中没有提前烘焙系统会再次处理的阴影、模糊或高光。

建议将背景、主体、文字和装饰拆成独立图层。不要提前加入最终遮罩，也不要把所有视觉效果合并为一张图片。这样才能分别检查 Default、Dark 和 Mono 外观。

官方示例中，iPhone、iPad 和 Mac 常见画布为 1024 × 1024，Apple Watch 示例为 1088 × 1088。这些是官方示例尺寸，不应当被理解为所有平台唯一可用的强制尺寸。图层组织通常建议控制在 4 个组以内，便于后续调整和排查。

文件创建与 Target 关联

新项目可以采用下面的最短路径：

1. 将 SVG 或 PNG 图层导入 Icon Composer。
2. 在画布中分别查看 Default、Dark 和 Mono。
3. 只启用项目真正支持的平台，避免误把其他平台变体当成 iOS 结果。
4. 保存为明确的 .icon 文件，例如 AppIcon.icon。
5. 将文件加入 Xcode Project navigator。
6. 在 Target 的 General 设置中检查 App Icon 字段。
7. 确认字段值与文件名一致，且没有误指向旧资源。
8. 在 File inspector 中确认 Target Membership。
9. 先运行模拟器构建，再查看安装后的桌面图标。

如果你使用 Finder 拖入文件，还要确认文件是否复制到了项目目录。远程构建时尤其要检查 Git 工作区中是否真的存在该文件，而不是只有本地工程引用。

旧 AppIcon 的保留策略

用了 Icon Composer 后，仍然可以保留旧 AppIcon，但“文件还在项目里”不等于“构建仍然使用它”。

存量项目应建立独立迁移分支：

• 主分支继续保留当前 AppIcon。
• 升级分支加入 Icon Composer 文件。
• 第一次构建不要删除旧资源。
• 对比最低部署版本设备上的图标。
• 对比新系统的 Default、Dark 和 Mono。
• 完成 Archive 和 TestFlight 后，再决定是否合并。

如果产品必须维持旧系统上的原始品牌图标，继续使用资产目录通常更容易控制。如果项目接受自动生成的兼容图标，再考虑切换到 Icon Composer。不要在没有截图、构建号和回退提交的情况下直接删除旧资源。

如果项目包含主 App、Widget、Notification Extension 或 macOS Target，还要逐个检查图标配置。主 Target 通过，不代表其他 Target 会自动得到同样结果。

低版本 iOS 的显示差异

低版本系统可能不会提供与新系统完全相同的图标外观或材质。构建工具可能根据 Icon Composer 文件生成面向旧系统的兼容图标，因此视觉不同不一定表示构建失败。

你需要判断的是：

• 主体轮廓是否仍然可识别。
• 文字或关键符号是否被裁切。
• 深色背景下是否失去边界。
• 图标是回退到了旧 AppIcon，还是使用了自动生成版本。
• 差异是否已经超过产品可接受范围。

若旧版用户必须看到原始图标，建议把传统资产目录保留到迁移完成。传统图标还可以针对 Light、Dark 和 Tinted 外观提供不同资源，适合对旧系统显示结果要求较高的项目。相关配置可参考 Xcode 的 App 图标配置说明。

Icon Composer 的优势是共享分层结构，但共享文件不代表所有平台都应该完全相同。

同一套图层在 iPhone、iPad、Mac 或 Apple Watch 上可能出现不同问题：

• 圆角或外框比例改变。
• 主体在遮罩后显得过小。
• Mac 上细节清楚，iPhone 桌面上却无法识别。
• Apple Watch 上的细线和小文字消失。
• Dark 或 Mono 外观压低颜色层次。
• 平台专属安全区域导致主体被裁切。

因此应区分“共享图层结构”和“平台专属调整”。可以共享背景、主体和品牌符号，但不必为了保持一个文件结构而牺牲某个平台的识别度。

同时，不要根据 Icon Composer 支持多平台，就自行推断所有 Apple 平台都适用同一流程。visionOS 等目标应继续按照对应官方规范处理，不要把未确认的平台支持写成确定结论。

工具链检查

截至 2026 年 8 月 29 日，Icon Composer 独立下载页面要求运行在 macOS Tahoe 26.4 或更高版本。当前发布记录显示 Apple 已发布 Xcode 27 beta 6，版本号为 27A5252f，发布日期为 2026 年 8 月 24 日；正式版状态仍应以后续发布页为准。不要把 Beta 行为当成最终提交规则。

远程 Mac 或自动构建节点至少检查以下项目：

• macOS 是否满足 Icon Composer 的系统要求。
• Xcode、SDK 与项目部署目标是否匹配。
• .icon 文件是否进入版本控制。
• 工程引用是否使用稳定路径。
• Target Membership 是否在远程工作区一致。
• Scheme 是否指向预期 App Target。
• Bundle ID、签名配置和 Archive 目标是否正确。
• 构建脚本是否运行在正确的项目目录。

找不到 Icon Composer 文件的排查顺序

远程构建时找不到文件，不要先清空所有缓存。按层排查更快：

1. 文件层：确认 Git 工作区实际存在 .icon 文件。
2. 工程层：检查 Xcode 工程是否存在有效文件引用。
3. Target 层：检查 Target Membership 和 App Icon 字段。
4. Scheme 层：确认 Archive 使用的 Target 与本地一致。
5. 工具链层：记录 macOS、Xcode 和 Icon Composer 版本。
6. 日志层：保留 actool、ibtool 和 Archive 日志。
7. 产物层：解包 .xcarchive 或导出 App，检查最终 Bundle 中的资源。

如果构建节点没有图形界面，重点不是能否打开 Icon Composer，而是 Xcode 的非交互式 Archive 能否正确读取已经纳入项目的文件。首次迁移建议先手动构建一次，再运行命令行 Archive，避免把工程引用错误和环境问题混在一起。

模拟器验收

• [ ] 安装新构建后，桌面图标不再是旧 AppIcon。
• [ ] Default 外观下主体轮廓清楚。
• [ ] Dark 外观下边界和对比度足够。
• [ ] Mono 外观下仍能识别品牌主体。
• [ ] 使用最低部署版本对应的模拟器记录兼容差异。
• [ ] 多平台 Target 分别安装，不只测试主 App。

真机验收

• [ ] 使用新系统设备检查外观切换。
• [ ] 使用最低部署版本范围内的设备或测试环境检查兼容图标。
• [ ] 从主屏幕、搜索、设置等位置观察图标。
• [ ] 检查浅色、深色和常用辅助显示设置。
• [ ] 记录裁切、模糊、透明度异常和主体过小等问题。
• [ ] 保存设备型号、系统版本和截图。

系统可能对图标应用额外的视觉效果。如果设计稿已经包含阴影、模糊或高光，实际显示可能出现叠加。必须在 Simulator 或真机上查看结果，不能只依据设计工具预览。

Archive 与 TestFlight 验收

• [ ] 使用发布配置完成 Archive。
• [ ] 检查 Scheme、Bundle ID、版本号和 Build 字符串。
• [ ] 确认 App Icon 设置指向预期 .icon 文件。
• [ ] 解包 Archive，确认 Bundle 内不是旧图标资源。
• [ ] 保存资源编译和归档阶段日志。
• [ ] 上传新的 Archive 并等待构建处理。
• [ ] 安装 TestFlight 版本，而不是直接运行 Xcode 调试版本。
• [ ] 删除旧安装后重新安装，避免缓存造成误判。
• [ ] 检查 TestFlight 页面和设备桌面是否显示预期图标。
• [ ] 记录构建号、设备、系统版本和截图。

App Store Connect 会根据 Bundle ID、版本号和 Build 字符串关联上传构建。上传成功不等于构建已经处理完成，也不等于可以直接提交审核。若构建长期处于 Processing，超过 24 小时仍未完成，就应查看处理状态和错误信息，而不是重复上传相同 Archive。具体状态可参考 App Store Connect 的构建上传状态说明。

只有以下条件全部满足，才适合从双轨维护切换到单一资源：

• .icon 文件已进入版本控制。
• Target 的 App Icon 字段指向正确文件。
• 旧 AppIcon 是否保留已经有明确决策。
• Default、Dark、Mono 外观均可识别。
• 最低部署版本的图标结果可接受。
• 模拟器和真机结果没有关键差异。
• Archive 中的 Bundle 资源正确。
• TestFlight 安装后不再显示旧图标。
• App Store Connect 中的构建已经完成处理。
• 团队保留了可回退提交和验收截图。

如果你目前依赖临时借用的 Mac、不同电脑之间手动同步 .icon 文件，或让 CI 节点长期保留多套不一致的 Xcode，真实缺点通常是环境漂移、文件遗漏、日志难以复现，以及低版本结果无法稳定重测。对于一次图标迁移或短期多版本验收，可以先在 CALMVPS 的远程 Mac 方案 上建立独立迁移分支，跑完 Archive 与 TestFlight，再决定是否购买硬件或保留常驻构建环境。需要长期运行构建任务时，再根据 CALMVPS 的方案与价格说明 分开核算短期验证和持续集成成本。