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

> ITMS-90717：构建里的 1024 x 1024 图标带有透明度或 alpha 通道。把它导出为不透明图标，用 sips 检查，再重新构建。

原始页面：[ITMS-90717 Expo 应用图标透明报错修复](https://devoria.fr/zh-hans/blog/itms-90717-invalid-large-app-icon-expo)
作者：[Mehdi Azizi](https://devoria.fr/zh-hans/mehdi-azizi)
发布：2026-11-04
内容最后修订：2026-11-04


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 关于图标的文档](https://developer.apple.com/documentation/xcode/configuring-your-app-icon)里写得很清楚：在 App Store 上分发的 App，必须在图片资源目录里提供 1024 点的图标。

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

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

## 用 sips 检查你的图标

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

```bash
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：

```bash
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。** 如果你装了它，可以自己选背景色：

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

根据 [ImageMagick 文档](https://imagemagick.org/command-line-options/#alpha)，`-alpha remove` 会把图片铺到背景色上，`-alpha off` 会关掉通道。

这三种方法都是用纯色填充透明区域。如果你的 logo 原本浮在透明背景上，最干净的做法是回到源文件，画一个真正的背景。Expo 在它的 [App 图标指南](https://docs.expo.dev/develop/user-interface/splash-screen-and-app-icon/)里也这么要求：图标要铺满整个正方形，不要圆角，不要透明像素。iOS 会自己加遮罩。

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

Expo 先读 `ios.icon`，再读配置根部的 `icon` 字段。根据 [Expo 配置参考](https://docs.expo.dev/versions/latest/config/app/)，`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 关于 [持续原生生成](https://docs.expo.dev/workflow/continuous-native-generation/) 的页面写明：如果项目里有 `android` 和 `ios` 文件夹，EAS Build 就不会运行 prebuild。**这时你的 app.json 就管不到图标了**：发给 Apple 的是 `ios` 文件夹里的 PNG。

在项目根目录检查一下：

```bash
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 指南](https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer)，Xcode 也会从中生成旧版 iOS 用的图片。

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

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

这种情况下，prebuild 原样复制文件夹，最终图标由 Xcode 生成。所以需要 Xcode 26 或更高版本，也就是较新的 EAS 镜像里用的那个，我在 [ITMS-90725](https://devoria.fr/zh-hans/blog/itms-90725-sdk-version-issue-expo) 的指南里讲过。

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

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

## 在最终构建里检查图标

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

```bash
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](https://devoria.fr/zh-hans/blog/itms-90683-missing-purpose-string-expo)，或者隐私清单的 [ITMS-91053](https://devoria.fr/zh-hans/blog/itms-91053-missing-api-declaration-expo)。构建通过后，用 [TestFlight](https://devoria.fr/zh-hans/blog/testflight-guide-test-iphone-app) 安装它，看看你的图标在主屏幕上的样子。

审核员的拒绝需要多退一步想：处理思路在 [App 被 Apple 拒绝](https://devoria.fr/zh-hans/expertise/app-rejected-by-apple) 这一页，最常见的原因在 [Apple 为什么拒绝 App](https://devoria.fr/zh-hans/blog/apple-app-rejection-reasons-real-cases) 里。

想在上传前检查你的项目，[Review Kit](https://devoria.fr/zh-hans/kits/app-review) 包含我的检查清单，以及会审阅你项目的 Claude Code skills。如果上传卡住了，想要有人帮你看看，[预约我一小时](https://devoria.fr/zh-hans/coaching)：我们视频连线，在你的屏幕上一起过你的项目。如果你在准备第一次上架，[做一下免费诊断](https://devoria.fr/zh-hans/diagnostic)：它会帮你理清步骤顺序，并发给你我的防 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。


## 你的项目

[Review Kit](https://devoria.fr/zh-hans/kits/app-review)：我的 App Store 审核清单、我被 Apple 拒审后的修正方案、Google Play 审核清单，以及三个 Claude Code skill。¥369。

[iOS & Android Kit](https://devoria.fr/zh-hans/kits/ios)：用 Claude Code 打造你的 iPhone 和 Android 应用：我自己应用的起步代码、上架商店的完整流程，以及全部工具包。¥739。

[诊断：你离自己的 iPhone 应用还差什么](https://devoria.fr/zh-hans/diagnostic)：7 个问题，60 秒：看清真正阻碍你发布 iPhone 应用的原因，拿到你的 4 步路线和适合你的套件。