RealWorld iOS 应用图标工程：AppIcon.appiconset 结构、Contents.json 清单与 iTunesArtwork 扩展名/透明度规范

本文围绕 RealWorld 仓库（"The mother of all demo apps"，多技术栈 Medium 风格演示应用）中的 iOS 图标资产目录 assets/media/mobile_icons/ios 展开。目录内自带的 README.md 是 makeAppIcon 类图标生成工具的标准说明文件，它只讲了两个点：iTunesArtwork 文件的 .png 扩展名在不同分发渠道下的取舍，以及透明像素在 App Store Connect 提交时会被转成纯黑的事实与对策。下文完整继承这两条规则，并结合目录中 26 个 PNG 实文件与 Contents.json 清单逐项核实尺寸、色彩类型与映射关系，帮助你在维护一套可上架、可 Ad Hoc 分发的 iOS 图标资产时避免踩坑。

1. 这套资产目录的来源与总体结构

assets/media/mobile_icons 目录是一套典型的 makeAppIcon 风格“一次生成、多平台产物”模板，iOS 部分包含：

• AppIcon.appiconset/：Xcode 的 App Icon Set 资产目录，含 26 个 PNG 和 Contents.json 清单；
• [e-mail]（512x512）、[e-mail]（1024x1024）、[e-mail]（1536x1536）：应用商店展示用的应用图标，注意本仓库实际保留了三个倍率版本，而 README 的标题只提到 @1x 与 @2x 两个——说明该 README 的文本略早于 @3x 资产的加入，但 README 所述规则对三者同样成立。

目录内没有脚本，只有静态 PNG 资产。从两份 Contents.json 的尾部元数据可以确认其生成来源——ios/AppIcon.appiconset/Contents.json 与 watchkit/AppIcon.appiconset/Contents.json 都以如下结构结尾：

"info": {
  "version": 1,
  "author": "makeappicon"
}

"author": "makeappicon" 表明这些清单是由 makeAppIcon 一类工具批量生成的。工具产物的三个标志在本目录中可以一一对照：@1x/@2x/@3x 倍率命名约定、多平台并列目录（android/mipmap-*、ios、watchkit、imessage），以及用 Contents.json 做“尺寸-文件”映射。理解这一点后，目录里所有文件名的模式都可以机械推导，不需要逐个记忆。

2. iTunesArtwork 的 .png 扩展名规则（README 第一条）

README 原文规则（见 assets/media/mobile_icons/ios/README.md）可以归纳为一张表：

分发渠道	iTunesArtwork / iTunesArtwork@2x 的文件名	原因
App Store Connect（iTunesConnect）提交	保留 .png 扩展名	Apple 官方文档曾建议这两个文件省略扩展名，但实际提交时 .png 扩展名是必需的，README 强调“我们已经替你做了，你不用再做”
Ad Hoc / Enterprise 分发（加入 Xcode 工程）	去掉 .png 扩展名	带扩展名的文件加入 Xcode 会报错

本仓库中三个文件当前均带 .png 扩展名（[e-mail]、[e-mail]、[e-mail]），即处于“面向 App Store Connect 提交”的状态。如果你的团队要出 Ad Hoc/Enterprise 测试包，把这三个文件重命名去掉 .png 后再拖进 Xcode 即可；两条规则互斥，不能同时满足，切换分发方式时必须重命名。

需要说明的适用前提：README 所依据的是 Apple 当年的 QA 文档（README 中的 refs 指向 Apple 开发者文档库的 QA1686 与 Mobile HIG 的 App Icons 页面）。本仓库只保留了规则结论与引用说明，未复制外部链接；实际 Apple 侧流程若已调整，应以当前 Xcode 版本的行为和 Apple 当期文档为准。

3. 透明像素转纯黑规则（README 第二条）

README 第二段说明：

• 带 alpha 通道（透明）的图片不能直接作为 App Store 上的应用图标；
• 提交 App Store Connect 时，图片中所有透明像素会被转换为纯黑色；
• 因此建议在用 makeAppIcon 类工具转换之前，先在源设计稿里处理好透明度（例如补实底背景），否则透明区域会以黑底出现。

本目录的资产可以直接印证这一设计的必要性：逐文件读取 PNG IHDR 头部（bit depth 与 color type）检查后，AppIcon.appiconset 内 26 个文件中有 24 个是 8-bit RGB（color type 2，无 alpha 通道），只有 [e-mail] 与 [e-mail] 两个 1x 尺寸文件是 RGBA（color type 6）。从文件结构看，这是生成工具对“图标必须不透明”这一约束的批量落实：绝大多数产物已经把 alpha 通道压掉了，只有个别小尺寸 1x 文件保留了 alpha。这也解释了 README 为什么把“透明变纯黑”作为提交前的关键检查项——一旦某个尺寸漏掉去透明处理，该尺寸上透明区域在商店里就会显示为黑色块。

三个 iTunesArtwork 文件同样是 8-bit RGB、无 alpha 通道，符合“商店图标不含透明像素”的要求。

4. AppIcon.appiconset 结构逐层解析

4.1 目录与文件命名

AppIcon.appiconset 是 Xcode 识别的 App Icon Set 目录，命名规则为 Icon-App-<逻辑尺寸>[@<倍率>].png，逻辑尺寸单位为 point。本目录 26 个文件的实测像素（读取自 PNG IHDR，与设计稿点尺寸×倍率逐一吻合）：

文件名	实测像素	idiom	size (pt)	scale	典型用途
[e-mail]	20x20	iphone	20x20	2x*	状态栏/小控件
[e-mail]	40x40	iphone	20x20	2x	状态栏
[e-mail]	60x60	iphone	20x20	3x	状态栏
[e-mail]	29x29	iphone	29x29	1x	Spotlight 搜索
[e-mail]	58x58	iphone	29x29	2x	Spotlight 搜索
[e-mail]	87x87	iphone	29x29	3x	Spotlight 搜索
[e-mail]	40x40	iphone	40x40	1x	Spotlight（低倍率屏）
[e-mail]	80x80	iphone	40x40	2x	Spotlight 搜索
[e-mail]	120x120	iphone	40x40	3x	Spotlight 搜索
[e-mail]	57x57	iphone	57x57	1x	主屏图标（旧机型）
[e-mail]	114x114	iphone	57x57	2x	主屏图标
[e-mail]	60x60	iphone	60x60	1x	主屏图标（iPhone）
[e-mail]	120x120	iphone	60x60	2x	主屏图标（iPhone）
[e-mail]	180x180	iphone	60x60	3x	主屏图标（iPhone）
[e-mail]	72x72	ipad	72x72	1x	主屏图标（旧 iPad）
[e-mail]	144x144	ipad	72x72	2x	主屏图标（iPad）
[e-mail]	76x76	ipad	76x76	1x	主屏图标（iPad）
[e-mail]	152x152	ipad	76x76	2x	主屏图标（iPad）
[e-mail]	228x228	ipad	76x76	3x	主屏图标（iPad Pro）
[e-mail]	167x167	ipad	83.5x83.5	2x	iPad 通知/锁屏小组件
[e-mail]	20x20	ipad	20x20	1x	iPad 状态栏
[e-mail]	40x40	ipad	20x20	2x	iPad 状态栏
[e-mail]	29x29	ipad	29x29	1x	iPad Spotlight
[e-mail]	58x58	ipad	29x29	2x	iPad Spotlight
[e-mail]	40x40	ipad	40x40	1x	iPad Spotlight
[e-mail]	80x80	ipad	40x40	2x	iPad Spotlight
[e-mail]	50x50	ipad	50x50	1x	旧式 iPad 小图标
[e-mail]	100x100	ipad	50x50	2x	旧式 iPad 小图标

上表中的 iPhone 20x20@1x 与 iPad 20x20 行共用同名文件（如 [e-mail] 同时出现在 iphone 与 ipad 两个 idiom 的条目里）；这是 makeappicon 产物常见做法——两个 idiom 指向同一个物理文件。同理 [e-mail]、[e-mail] 也分别被 iphone 与 ipad 条目重复引用。所以物理文件 26 个，清单条目 26 条中有 3 个 iphone/ipad 共名文件被双重引用（iphone 20x20@1x 条目实际引用了与 ipad 同名的 20x20@1x 文件）。

注意 [e-mail] 的小数点尺寸：83.5pt x 2 = 167px，文件名中的 83.5 是点尺寸的一部分，不是笔误。Xcode 10 引入的 iPad 通知/锁屏小组件图标就是这个尺寸。

4.2 Contents.json 条目格式

Contents.json 的 images 数组中每个条目只有四个关键字段（不含 role/subtype，那是 watchOS 特有的，见第 5 节）：

{
  "images": [
    {
      "idiom": "iphone",
      "size": "20x20",
      "scale": "2x",
      "filename": "[e-mail]"
    },
    {
      "idiom": "ipad",
      "size": "83.5x83.5",
      "scale": "2x",
      "filename": "[e-mail]"
    }
  ],
  "info": {
    "version": 1,
    "author": "makeappicon"
  }
}

字段含义：

• idiom：iphone 或 ipad，决定该尺寸在哪个平台生效；
• size：逻辑点尺寸（字符串形式，如 "20x20"），与物理像素无关；
• scale：1x/2x/3x 视网膜倍率，物理像素 = 点尺寸 × 倍率；
• filename：AppIcon.appiconset 目录内的物理文件名，清单与文件一一（或一对多，见上文共名引用）对应。

维护这份清单时的操作要点：新增/删除文件必须同步改 images 数组，否则 Xcode 会报缺失图标；size/scale 与文件名必须自洽（例如 "60x60" + "3x" 必须对应 180x180 像素的文件），本目录 26 个文件全部自洽，可直接作为对照样例。

5. 对照：watchOS 清单中的 role/subtype 与 iMessage 产物

同仓库的 watchkit/AppIcon.appiconset/Contents.json 是同一套工具的另一产物，可以对照看出 iOS 与 watchOS 清单的差异。watch 条目在 idiom/size/scale/filename 之外还多了 role 与 subtype：

{
  "size": "40x40",
  "idiom": "watch",
  "scale": "2x",
  "filename": "[e-mail]",
  "role": "appLauncher",
  "subtype": "38mm"
}

role 取值如 appLauncher（表盘启动器）、quickLook（抬起手腕快速查看）、notificationCenter、longLook、companionSettings；subtype 区分 38mm/42mm 表款。iOS 清单不需要这两个字段，因为 iPhone/iPad 的用途由尺寸+倍率隐含决定。

再看 imessage 子目录：[e-mail]（27x20）到 icon-messages-app-store-1024x768.png（1024x768），命名模式 icon-messages-app-<逻辑尺寸>@<倍率>.png 与 App Icon 的 @Nx 约定同源，但 iMessage 贴图的逻辑尺寸是 27x20pt 而非正方形，说明这套生成工具对“不同用途、不同画幅”的图标是统一按同一命名约定批量输出的。android 子目录则按 mipmap 密度分层（ldpi 36px 到 xxxhdpi 192px 的 ic_launcher.png 加 playstore-icon.png 512px），同样全部为 8-bit RGB。

6. 实践要点汇总

结合 README.md 的两条规则与本目录的实物验证，维护这套图标资产的操作清单：

1. 提交 App Store Connect 前：确认三个 iTunesArtwork*@Nx.png 带 .png 扩展名（当前仓库状态即是）；确认目标尺寸文件无透明像素（本目录 24/26 的 App Icon 与 3/3 的 iTunesArtwork 为无 alpha 的 RGB，仅 2 个 1x 小尺寸 App Icon 保留 alpha，若它们对应尺寸会被商店使用，建议按 README 建议回到源设计稿处理透明度后重新生成）。
2. Ad Hoc/Enterprise 分发前：把 iTunesArtwork/iTunesArtwork@2x（及 @3x）去掉 .png 扩展名再加入 Xcode，避免报错。
3. 改图标时：先改源设计稿（补齐透明区域），再用 makeAppIcon 类工具重新生成 AppIcon.appiconset 与 iTunesArtwork 三个倍率文件，保持文件名模式与 Contents.json 中 size×scale 的像素自洽。
4. 核对产物：PNG IHDR 头部前 26 字节即可读出宽高、bit depth 与 color type（color type 2 = RGB 不透明，6 = RGBA 带透明），本目录所有文件经此核对均与设计稿尺寸一致，可作为验收方法参考。

适用前提：以上规则以本仓库 assets/media/mobile_icons/ios 目录的实际内容与 README.md 原文为准，面向 iOS App 图标的上架/分发场景；README 引用的 Apple 文档为历史 QA 页面，具体 Apple 侧要求以你所用 Xcode 版本及当期 Apple 文档为准。