ITMS-90717 Expo 应用图标透明报错修复

ITMS-90717 是 Apple 对你的构建做的一项自动检查。它的意思是：App 的大图标，也就是 App Store 上展示的那张 1024 x 1024 像素的图标，包含透明度或 alpha 通道。解决办法：做一张正方形、不透明、不带 alpha 通道导出的图标，然后重新构建。

用 Expo 的话，问题很少出在你的 PNG 文件本身：prebuild 已经会把它铺在白色背景上。我读过 SDK 57 里的这段代码，也检查了 Solys、TradaZen 和 Nolera 的图标。所以报错多半来自纳入版本控制的 ios 文件夹，或者 Icon Composer 文件。下面讲怎么找出是哪一个，以及怎么修。

ITMS-90717 报错是什么意思？

报错标题是“ITMS-90717: Invalid large app icon”。它说明你 App 图片资源目录里的大图标“can't be transparent or contain an alpha channel”：不能透明，也不能包含 alpha 通道。以前的报错写的是“Invalid App Store Icon”，规则是同一条。

这张大图标就是 App Store 用的那张。Xcode 关于图标的文档里写得很清楚：在 App Store 上分发的 App，必须在图片资源目录里提供 1024 点的图标。

alpha 通道是 PNG 的第四层，和红、绿、蓝并列，存的是每个像素的透明度。一张图标看上去是满的，也可能还带着这个通道：这就是论坛里每个帖子都会踩的坑。

和其他 ITMS 错误一样，这不是审核员拒绝的。是 Apple 在交付时分析了二进制文件。根据你用的上传工具，这个错误会显示为验证失败，比如带 409 代码。

用 sips 检查你的图标

Mac 上自带 sips。一行命令就够：

sips -g hasAlpha assets/icon.png

你希望看到 hasAlpha: no。2026 年 10 月 15 日，我对 Solys、TradaZen 和 Nolera 的 app.json 里声明的图标跑了这条命令：全部返回 no，尺寸都是 1024 x 1024。

我还做了一张测试图标：一个完全不透明的蓝色方块，但保存时带了 alpha 通道。sips 返回 yes。没有一个像素是透明的，通道却还在。这就是为什么那么多开发者在这条报错下面留言“我的图标根本没有透明”。

在“预览”(Preview) 里，检查器（Tools，Show Inspector）也会列出图片属性，包括 alpha 通道。

修复：导出不带 alpha 通道的图标

三种方法，从最简单到最精细。

1. 预览。 File，Export，格式选 PNG，然后取消勾选 Alpha。导出的文件就没有 alpha 通道了。

2. sips，不用装任何东西。 sips 没法直接去掉 PNG 的 alpha 通道。要先转成没有 alpha 的 JPEG：

sips -s format jpeg -s formatOptions 100 icon.png --out icon.jpg
sips -s format png icon.jpg --out icon-opaque.png
sips -g hasAlpha icon-opaque.png

在我那张四角透明的测试图标上，四角变成了白色，最后一行返回 no。转 JPEG 即使用最高质量也会有一点压缩：仔细看看结果。

3. ImageMagick。 如果你装了它，可以自己选背景色：

magick icon.png -background white -alpha remove -alpha off icon-opaque.png

根据 ImageMagick 文档，-alpha remove 会把图片铺到背景色上，-alpha off 会关掉通道。

这三种方法都是用纯色填充透明区域。如果你的 logo 原本浮在透明背景上，最干净的做法是回到源文件，画一个真正的背景。Expo 在它的 App 图标指南里也这么要求：图标要铺满整个正方形，不要圆角，不要透明像素。iOS 会自己加遮罩。

Expo 从哪里取图标，又怎么处理它

Expo 先读 ios.icon，再读配置根部的 icon 字段。根据 Expo 配置参考，ios.icon 接受三种形式：一个 PNG，一个带 light、dark 和 tinted 变体的对象，或者一个用 Icon Composer 创建的 .icon 文件夹。

下表来自 prebuild 时生成 iOS 图标的代码，@expo/prebuild-config 57.0.16（SDK 57），阅读日期 2026 年 10 月 15 日：

你声明的内容	prebuild 的处理	ITMS-90717 风险
PNG 格式的 icon	铺到白底上	低
ios.icon.light	铺到白底上	低
ios.icon.tinted	铺到白底上	低
ios.icon.dark	保留透明	Apple 的要求
.icon 格式的 ios.icon	原样复制	真实存在
纳入版本控制的 ios 文件夹	不重新跑 prebuild	真实存在

用 PNG 时，Expo 会自己去掉透明，换成白色。所以一个抠好图的 logo 最后会落在白色方块上：不会报错，但效果可能不是你想要的。深色变体保留透明，这是故意的：Apple 要求深色图标用透明背景，好让系统提供的背景透出来。

Nolera 声明了三种变体，sips 对生成的浅色和着色图标返回 no，对深色图标返回 yes。从这些变体的提交日期看，已上线的 1.0.2 版本包含了它们。我没有在它的 IPA 里核实。

纳入版本控制的 ios 文件夹

这是 Expo 项目最可能的原因。Expo 关于 持续原生生成 的页面写明：如果项目里有 android 和 ios 文件夹，EAS Build 就不会运行 prebuild。这时你的 app.json 就管不到图标了：发给 Apple 的是 ios 文件夹里的 PNG。

在项目根目录检查一下：

sips -g hasAlpha ios/*/Images.xcassets/AppIcon.appiconset/*.png

如果 1024 那张图标返回 yes，就用你的不透明版本替换它，文件名保持不变。如果你没有手动改过任何原生代码，也可以删掉 ios 文件夹，把它加进 .gitignore：EAS 每次构建都会重新生成。在 Solys、TradaZen 和 Nolera 上，这个文件夹都被 git 忽略了。

iOS 26 的格式：Icon Composer

Icon Composer 是 Apple 为 iOS 26 的 Liquid Glass 图标推出的工具。它生成一个多图层的 .icon 文件。根据 Apple 的 Icon Composer 指南，Xcode 也会从中生成旧版 iOS 用的图片。

Expo 从 SDK 54 开始支持它。你要用字符串声明这个文件夹，不要放进变体对象里：

{
  "expo": {
    "ios": {
      "icon": "./assets/app.icon"
    }
  }
}

这种情况下，prebuild 原样复制文件夹，最终图标由 Xcode 生成。所以需要 Xcode 26 或更高版本，也就是较新的 EAS 镜像里用的那个，我在 ITMS-90725 的指南里讲过。

从 2025 年 8 月起，Apple 开发者论坛上就有帖子报告 .icon 文件触发 ITMS-90717。大家提到的可能原因：一个透明的 PNG 图层，一个比画布大的图层，一个靠近边缘、带 Blur 效果的组。提到的绕过办法：关掉 Blur，保留实心背景，或者退回 PNG。这些帖子里没有 Apple 的官方修复，到 2026 年 8 月仍有人报告这个错误。

Apple 的图标规范也是这个方向：如果你导入背景图层，它必须覆盖整个区域并且不透明。我的 App 还在用 PNG，所以没有在生产环境测试过 Icon Composer。如果 .icon 文件卡住了你的上传，把 ios.icon 改回 PNG：Expo 会把它铺平，你的图标就能过这项检查。

在最终构建里检查图标

在 IPA 里，1024 图标不是 PNG 文件：Xcode 把它编译进了 Assets.car。从 expo.dev 上的构建页面下载 IPA，然后运行：

unzip -q MyApp.ipa -d ipa
xcrun assetutil --info ipa/Payload/*.app/Assets.car | grep -B3 '"RenditionName" : "App-Icon'

每个图标都会显示一个 Opaque 字段。2026 年 10 月 15 日，我用 Xcode 的工具 actool 编译了 Solys 的图标和我那张四角透明的测试图标。前者输出 "Opaque" : true，后者输出 "Opaque" : false。Apple 没有记录这个字段：把它当作线索，而不是 Apple 的检查本身。

有个坑要知道：**不要用 sips 去测 App 根目录下那些小 PNG。**即使源图不透明，Xcode 写出它们时也会带 alpha 通道。在我用 Solys 图标做的测试里，sips 对它们返回 yes。

其他图标错误

代码	Apple 报告的问题	Expo 下的排查方向
ITMS-90717	1024 图标透明	不带 alpha 导出
ITMS-90704	缺少 1024 图标	缺少 1024 条目
ITMS-90022	缺少 iPhone 图标	资源目录不完整
ITMS-90023	缺少 iPad 图标	资源目录不完整

后三条报错主要出现在 2017 和 2018 年，那时 Xcode 9 改了图标规则。

用 Expo 的话，它们已经很少见了。prebuild 只写一张 1024 的通用图标，其他尺寸由 Xcode 生成。如果没有声明图标，Expo 甚至会生成一个白色方块，避免上传失败。如果遇到其中某个错误，去看纳入版本控制的 ios 文件夹：AppIcon.appiconset 里的 Contents.json 文件必须有一个尺寸为 1024x1024 的条目，而且它引用的 PNG 必须存在。

下次上传之前

图标十分钟就能修好，但每次报错都要浪费一次构建。其他自动检查也需要同样仔细，比如权限说明文字的 ITMS-90683，或者隐私清单的 ITMS-91053。构建通过后，用 TestFlight 安装它，看看你的图标在主屏幕上的样子。

审核员的拒绝需要多退一步想：处理思路在 App 被 Apple 拒绝 这一页，最常见的原因在 Apple 为什么拒绝 App 里。

想在上传前检查你的项目，Review Kit 包含我的检查清单，以及会审阅你项目的 Claude Code skills。如果上传卡住了，想要有人帮你看看，预约我一小时：我们视频连线，在你的屏幕上一起过你的项目。如果你在准备第一次上架，做一下免费诊断：它会帮你理清步骤顺序，并发给你我的防 Apple 拒审检查清单。

常见问题

我的图标根本没有透明，为什么 Apple 说有 alpha 通道？

因为即使所有像素都不透明，PNG 也可能保留 alpha 通道。很多工具导出时默认会加上它。用 sips -g hasAlpha 检查，然后不带这个通道重新导出图标。

能用远程更新修复 ITMS-90717 吗？

不能。图标被编译进了二进制文件里的 Assets.car。远程更新只能改 JavaScript 和 App 的资源。修好图标，重新构建，再重新提交。

深色图标可以透明吗？

可以。Apple 要求深色变体用透明背景，Expo 也会保留它的透明。我推断这项检查针对的是主图标，也就是 App Store 用的那张：必须不透明的是它。

iOS 图标需要做圆角吗？

不需要。提供一个铺满的正方形：iOS 会自己加遮罩。圆角会在四角留下透明像素，正是这项检查拒绝的东西。

Expo 支持 iOS 26 的 Icon Composer 图标吗？

支持，从 SDK 54 开始：在 ios.icon 里用字符串声明 .icon 文件夹的路径。prebuild 原样复制，Xcode 26 负责编译。如果这种格式遇到 ITMS-90717，检查透明图层和 Blur 效果，或者暂时退回 PNG。