# ITMS-90717 錯誤修正：Expo App 圖示透明問題

> ITMS-90717 代表你 build 裡的 1024 x 1024 圖示還有透明度或 Alpha 色版。把它輸出成不透明圖片，用 sips 檢查，再重新 build。

原始頁面：[ITMS-90717 錯誤修正：Expo App 圖示透明問題](https://devoria.fr/zh-hant/blog/itms-90717-invalid-large-app-icon-expo)
作者：[Mehdi Azizi](https://devoria.fr/zh-hant/mehdi-azizi)
發布日期：2026-11-04
內容最後修訂：2026-11-04


ITMS-90717 是 Apple 對你的 build 做的自動檢查。它的意思是：App 的大圖示，也就是 App Store 上顯示的那張 1024 x 1024 像素圖示，含有透明度或 Alpha 色版。**解法：準備一張正方形、不透明、輸出時不帶 Alpha 色版的圖示，然後重新 build。**

用 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 point 的圖示。

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`。**沒有任何像素是透明的，色版卻還在。** 這就是為什麼這麼多開發者在這則訊息下面留言「我的圖示根本沒有透明」。

在「預覽程式」裡，檢閱器（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 風險 |
| --------------------------- | ----------------- | --------------- |
| `icon` 為 PNG               | 平面化鋪在白底    | 低              |
| `ios.icon.light`            | 平面化鋪在白底    | 低              |
| `ios.icon.tinted`           | 平面化鋪在白底    | 低              |
| `ios.icon.dark`             | 保留透明度        | Apple 的要求    |
| `ios.icon` 為 `.icon`       | 原封不動複製      | 確實存在        |
| 納入版本控制的 `ios` 資料夾 | 不會重跑 prebuild | 確實存在        |

**用 PNG 的話，Expo 會自己移除透明度，換成白色。** 所以去背的 logo 最後會放在白色正方形上：不會報錯，但效果可能不是你想要的。深色變體會保留透明度，這是刻意的：Apple 要求深色圖示使用透明背景，讓系統提供的背景能顯示出來。

Nolera 宣告了三種變體，`sips` 對產生出來的淺色和著色圖示回應 `no`，對深色圖示回應 `yes`。根據這些變體的 commit 日期，已上架的 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 每次 build 都會重新產生。在 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-hant/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 會把它平面化，你的圖示就能通過這項檢查。

## 在最終 build 裡檢查圖示

在 IPA 裡，1024 圖示不是 PNG 檔：Xcode 會把它編譯進 `Assets.car`。從 expo.dev 的 build 頁面下載 IPA，然後執行：

```bash
unzip -q YourApp.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 必須存在。

## 下次上傳之前

圖示十分鐘就能修好，但每次出錯都要多花一次 build。其他自動檢查也需要同樣嚴謹，例如權限說明文字的 [ITMS-90683](https://devoria.fr/zh-hant/blog/itms-90683-missing-purpose-string-expo)，或隱私權清單的 [ITMS-91053](https://devoria.fr/zh-hant/blog/itms-91053-missing-api-declaration-expo)。build 被接受之後，用 [TestFlight](https://devoria.fr/zh-hant/blog/testflight-test-iphone-app-before-review) 安裝它，看看你的圖示在主畫面上的樣子。

審核人員的拒絕就需要多想一下：處理流程在 [App 被 Apple 拒絕](https://devoria.fr/zh-hant/expertise/app-rejected-by-apple)這一頁，最常見的原因則在 [Apple 為什麼拒絕 App](https://devoria.fr/zh-hant/blog/apple-app-rejection-reasons-real-cases)。

要在上傳前檢查你的專案，[Review Kit](https://devoria.fr/zh-hant/kits/app-review) 整合了我的檢查清單，以及會幫你審視專案的 Claude Code skills。如果你的上傳卡住了，想找真人看一下，[跟我預約一小時](https://devoria.fr/zh-hant/coaching)：我們透過視訊，在你的螢幕上一起看你的專案。如果你正在準備第一次上架，[來做免費診斷](https://devoria.fr/zh-hant/diagnostic)：它會幫你把步驟排好順序，並寄給你我的 Apple 防拒絕檢查清單。

## 常見問題

### 為什麼我的圖示完全沒有透明，Apple 卻說有 Alpha 色版？

因為即使所有像素都不透明，PNG 仍可能保留 Alpha 色版。很多工具輸出時預設就會加上。用 `sips -g hasAlpha` 檢查，再把圖示重新輸出成不帶這個色版的版本。

### 可以用遠端更新修正 ITMS-90717 嗎？

不行。圖示是編譯進二進位檔裡的 `Assets.car`。遠端更新只會改 JavaScript 和 App 的資源。修好圖示，重新 build，再重新上傳。

### 深色圖示可以是透明的嗎？

可以。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-hant/kits/app-review)：我的 App Store 審查檢查清單、我被 Apple 退件後的修正、Google Play 檢查清單，以及三個 Claude Code skill。$1,749。

[iOS & Android Kit](https://devoria.fr/zh-hant/kits/ios)：用 Claude Code 打造你的 iPhone 和 Android App：我自己 App 的起始程式碼、上架商店的完整流程，以及所有套件。$3,599。

[診斷：你離自己的 iPhone App 還差什麼](https://devoria.fr/zh-hant/diagnostic)：7 個問題，60 秒：找出真正卡住你發布 iPhone App 的原因，拿到你的 4 步驟路線，以及最適合你的套件。