文章目录
- 快速导航
ITMS-90717 图标报错怎么解决：App Store 图标不能透明、不能含 Alpha 通道
报错长什么样
用 Xcode Archive 后上传，或用 Transporter、altool 提交时，可能遇到下面任一提示：
ERROR ITMS-90717: "Invalid App Store Icon. The App Store Icon in the asset catalog in 'YourApp.app' can't be transparent nor contain an alpha channel."Asset validation failed (90717) Invalid large app icon. The large app icon in the asset catalog in "YourApp.app" can't be transparent or contain an alpha channel.
两种写法是同一个问题：App Store 用的 1024×1024 营销图标（App Store Icon / large app icon）带了透明通道。哪怕图片看上去四角都填满了，只要 PNG 文件里存在 Alpha 通道，校验也会失败。
图标的圆角遮罩和导出规范见 iOS 图标圆角与遮罩指南，本文只解决这个报错。
为什么会带上 Alpha
| 来源 | 典型情况 |
|---|---|
| 设计软件默认导出 | Figma、Sketch、Photoshop 导出 PNG 时保留透明通道 |
| 设计稿自带圆角 | 设计师把圆角和透明四角一起导出 |
| 自动生成图标的工具 | 跨平台框架的图标生成器从带透明的源图生成全部尺寸 |
| 图片被二次处理 | 压缩工具把 RGB 转成 RGBA |
第一步：确认是不是 Alpha 问题
在 macOS 终端进入图标目录（通常在 Assets.xcassets/AppIcon.appiconset/），运行：
sips -g pixelWidth -g pixelHeight -g hasAlpha *.png
看到 hasAlpha: yes 的文件就是问题来源。如果装了 ImageMagick，也可以：
magick identify -format "%f %wx%h %[channels]\n" *.png
输出里出现 srgba 之类带 a 的通道描述，就说明含 Alpha。
第二步：去掉 Alpha 的几种方法
| 方法 | 操作 | 适合 |
|---|---|---|
| macOS 预览 | 打开图标 → 文件 → 导出 → 取消勾选「Alpha」→ 存储 | 单个文件，最快 |
| ImageMagick | magick icon.png -background white -alpha remove -alpha off icon.png | 批量处理 |
| Python Pillow | Image.open("icon.png").convert("RGB").save("icon.png") | 脚本化流程 |
| 设计软件重导出 | 给画板加满版不透明背景，导出为无透明 PNG 或 JPG 再转 PNG | 从源头修复 |
注意：
-background的颜色要和图标底色一致，否则原来透明的部分会变成白边或黑边。最好的做法是在设计稿里就把背景铺满，而不是事后补色。- 图标应是直角方形、满版交付，由系统加圆角。不要自己画圆角再填背景，否则会出现「圆角外一圈底色」。
- 批量处理前先备份原文件。
跨平台框架的修法
| 框架 | 处理方式 |
|---|---|
| Flutter（flutter_launcher_icons） | 在配置里设置 remove_alpha_ios: true，重新生成图标 |
| Expo / React Native | 换成无透明的源图（app.json 里的 icon），重新 prebuild 或构建 |
| Ionic / Capacitor | 用无透明源图重新生成资源，或对 AppIcon.appiconset 批量去 Alpha |
| Unity | 在 Player Settings 里换成不透明图标，检查导入设置未保留 Alpha |
修完后一定要重新 Archive，旧的 Archive 里还是旧图标。
深色和着色图标是例外
iOS 18 起支持深色（Dark）和着色（Tinted）外观图标。苹果的说明是：深色图标应使用透明背景，让系统提供的背景透出来。所以：
- 默认（Any Appearance）图标：必须不透明，不能含 Alpha；
- 深色图标：按苹果要求可以用透明背景；
- 着色图标：使用灰度图，同样建议不透明。
如果你加了深色图标后报 90717，先检查是不是默认图标或着色图标带了 Alpha，而不是去掉深色图标的透明。使用 Xcode 26 的 Icon Composer 分层图标时，图层本身可以是透明素材，由工具合成，详见 Liquid Glass 图标适配教程。
相关报错一并排查
| 报错 | 含义 | 处理 |
|---|---|---|
| ITMS-90717 | 营销图标透明或含 Alpha | 按本文去 Alpha |
| ITMS-90704 Missing Marketing Icon | 缺少 1024×1024 PNG 图标 | 在 AppIcon 里补上 1024 图 |
| 图标尺寸不符 | 放进槽位的图不是要求的像素 | 按槽位尺寸重导，或用 Xcode 单一尺寸模式 |
Xcode 14 起可以在 AppIcon 里只提供一张 1024×1024 图，由 Xcode 生成其他尺寸，能减少「某个小尺寸带 Alpha」的情况。
为什么本地运行正常、上传才报错
模拟器和真机调试时，系统并不会校验营销图标是否含 Alpha，主屏幕上的图标看起来也完全正常，所以这个问题往往拖到第一次上传 TestFlight 或提交审核时才暴露。几个容易被忽略的点：
- 校验发生在 App Store Connect 接收构建的环节，报错会出现在 Xcode Organizer 的上传结果或邮件通知里；
- 同一个图标文件被多个 target（主 App、小组件扩展、App Clip）引用时，每个 target 都可能单独报错；
- 换了图标但没有清理构建缓存，偶尔会把旧资源打包进去，必要时执行 Product → Clean Build Folder 后再 Archive。
防止再犯：把检查放进流程
修好一次之后，建议把检查自动化，避免下次设计师更新图标时再踩坑：
| 做法 | 说明 |
|---|---|
| 提交前脚本 | 在 Git pre-commit 或构建脚本里对 AppIcon.appiconset 运行 sips -g hasAlpha，发现 yes 就中止 |
| CI 检查 | 在持续集成里加一步同样的检查，失败时阻止打包 |
| 设计交付规范 | 和设计师约定：App Store 图标交付「1024×1024、不透明、直角满版」 |
| 单一来源 | 只维护一张 1024 源图，其余尺寸由 Xcode 或脚本生成 |
提交前自查清单
- 1024×1024，PNG，hasAlpha: no
- 直角方形、满版背景，没有自画圆角
- 色彩空间为 sRGB 或 Display P3
- 深色图标透明背景、默认图标不透明
- 修改后重新 Archive 再上传
小结
ITMS-90717 只有一个根因：默认营销图标里有 Alpha 通道。用 sips 定位文件，用预览、ImageMagick 或框架配置去掉 Alpha，在设计源文件里铺满背景，重新 Archive 即可。