# ITMS-90717: sửa lỗi Invalid large app icon với Expo

> ITMS-90717: icon 1024 x 1024 trong build còn độ trong suốt hoặc kênh alpha. Xuất lại icon không trong suốt, kiểm tra bằng sips rồi build lại.

Trang gốc: [ITMS-90717: sửa lỗi Invalid large app icon với Expo](https://devoria.fr/vi/blog/itms-90717-invalid-large-app-icon-expo)
Tác giả: [Mehdi Azizi](https://devoria.fr/vi/mehdi-azizi)
Ngày đăng: 2026-11-04
Lần sửa nội dung gần nhất: 2026-11-04


ITMS-90717 là một bước kiểm tra tự động của Apple trên build của bạn. Lỗi này báo rằng icon lớn của app, tức icon 1024 x 1024 pixel hiển thị trên App Store, có độ trong suốt hoặc có kênh alpha. **Cách sửa: một icon vuông, không trong suốt, được xuất ra không có kênh alpha, rồi build lại.**

Với Expo, file PNG của bạn hiếm khi là thủ phạm: bước prebuild đã đặt nó lên nền trắng. Mình đã đọc đoạn code này trong SDK 57 và kiểm tra icon của Solys, TradaZen và Nolera. Khi đó lỗi thường đến từ thư mục `ios` được đưa vào git hoặc từ một file Icon Composer. Dưới đây là cách tìm ra nguyên nhân và sửa nó.

## Lỗi ITMS-90717 nghĩa là gì?

Thông báo có tiêu đề "ITMS-90717: Invalid large app icon". Nó nói rõ icon lớn trong asset catalog của app "can't be transparent or contain an alpha channel": không được trong suốt và không được chứa kênh alpha. Các thông báo cũ hơn ghi "Invalid App Store Icon". Vẫn là cùng một quy tắc.

Icon lớn này chính là icon của App Store. [Tài liệu Xcode về icon](https://developer.apple.com/documentation/xcode/configuring-your-app-icon) giải thích: một app phân phối trên App Store phải cung cấp icon 1024 point trong asset catalog của nó.

Kênh alpha là lớp thứ tư của file PNG, bên cạnh đỏ, xanh lá và xanh dương. Nó lưu độ trong suốt của từng pixel. **Một icon có thể trông kín hoàn toàn mà vẫn giữ kênh này**: đây là cái bẫy lặp lại trong mọi topic trên diễn đàn.

Giống các lỗi ITMS khác, đây không phải là reviewer từ chối app. Apple đã phân tích file binary lúc bạn gửi lên. Tùy công cụ gửi, lỗi xuất hiện dưới dạng validation thất bại, ví dụ với mã 409.

## Kiểm tra icon bằng sips

Trên Mac, `sips` có sẵn. Chỉ cần một dòng:

```bash
sips -g hasAlpha assets/icon.png
```

Kết quả bạn muốn thấy là `hasAlpha: no`. Ngày 15 tháng 10 năm 2026, mình chạy lệnh này trên các icon khai báo trong app.json của Solys, TradaZen và Nolera: tất cả đều trả về `no`, ở kích thước 1024 x 1024.

Mình cũng làm một icon thử: một hình vuông xanh hoàn toàn không trong suốt, nhưng được lưu kèm kênh alpha. `sips` trả về `yes`. **Không pixel nào trong suốt, vậy mà kênh alpha vẫn ở đó.** Đó là lý do rất nhiều developer viết "icon của tôi không hề có chỗ nào trong suốt" bên dưới thông báo này.

Trong Preview, Inspector (Tools, Show Inspector) cũng liệt kê các thuộc tính của ảnh, trong đó có kênh alpha.

## Cách sửa: xuất icon không có kênh alpha

Ba cách, từ đơn giản nhất đến chính xác nhất.

**1. Preview.** File, Export, chọn định dạng PNG, rồi bỏ chọn ô Alpha. File xuất ra không còn kênh alpha.

**2. sips, không cần cài gì.** `sips` không xóa được kênh alpha của file PNG. Bạn phải đi vòng qua JPEG, định dạng không có kênh alpha:

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

Với icon thử có góc trong suốt của mình, các góc chuyển thành màu trắng và dòng cuối trả về `no`. Việc đi qua JPEG làm ảnh bị nén một chút, kể cả ở chất lượng tối đa: hãy xem kỹ kết quả.

**3. ImageMagick.** Nếu đã cài, bạn tự chọn được màu nền:

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

Theo [tài liệu ImageMagick](https://imagemagick.org/command-line-options/#alpha), `-alpha remove` đặt ảnh lên màu nền, còn `-alpha off` tắt kênh alpha.

Cả ba cách đều lấp vùng trong suốt bằng một màu đồng nhất. Nếu logo của bạn vốn nằm trên nền trong suốt, cách gọn gàng nhất là mở lại file gốc và vẽ một nền thật. Expo yêu cầu điều này trong [hướng dẫn về icon app](https://docs.expo.dev/develop/user-interface/splash-screen-and-app-icon/): icon phải lấp kín cả hình vuông, không bo góc, không có pixel trong suốt. iOS sẽ tự áp mask.

## Expo lấy icon của bạn ở đâu và làm gì với nó

Expo đọc `ios.icon` trước, sau đó đến trường `icon` ở gốc cấu hình. Theo [tài liệu tham chiếu cấu hình Expo](https://docs.expo.dev/versions/latest/config/app/), `ios.icon` nhận ba dạng: một file PNG, một object với các biến thể `light`, `dark` và `tinted`, hoặc một thư mục `.icon` tạo bằng Icon Composer.

Bảng dưới đây lấy từ đoạn code tạo icon iOS lúc prebuild, `@expo/prebuild-config` 57.0.16 (SDK 57), mình đọc ngày 15 tháng 10 năm 2026:

| Bạn khai báo gì         | Prebuild làm gì          | Rủi ro ITMS-90717 |
| ----------------------- | ------------------------ | ----------------- |
| `icon` dạng PNG         | Làm phẳng trên nền trắng | Thấp              |
| `ios.icon.light`        | Làm phẳng trên nền trắng | Thấp              |
| `ios.icon.tinted`       | Làm phẳng trên nền trắng | Thấp              |
| `ios.icon.dark`         | Giữ độ trong suốt        | Apple yêu cầu     |
| `ios.icon` dạng `.icon` | Sao chép nguyên trạng    | Có thật           |
| Thư mục `ios` trong git | Không chạy lại prebuild  | Có thật           |

**Với file PNG, Expo tự xóa độ trong suốt và thay bằng màu trắng.** Một logo đã tách nền vì vậy sẽ nằm trên hình vuông trắng: không có lỗi, nhưng có thể không phải kết quả bạn muốn. Biến thể tối giữ độ trong suốt, và điều đó là có chủ ý: Apple yêu cầu nền trong suốt cho icon tối để nền do hệ thống cung cấp hiện ra.

Với Nolera, app khai báo cả ba biến thể, `sips` trả về `no` cho icon sáng và icon tinted được tạo ra, `yes` cho icon tối. Dựa vào ngày commit các biến thể này, phiên bản 1.0.2 đang phát hành có chứa chúng. Mình chưa kiểm tra trong file IPA.

### Trường hợp thư mục ios được đưa vào git

Đây là nguyên nhân khả dĩ nhất với Expo. [Trang của Expo về continuous native generation](https://docs.expo.dev/workflow/continuous-native-generation/) nói rõ: nếu dự án chứa thư mục `android` và `ios`, EAS Build sẽ không chạy prebuild. **Lúc đó app.json không còn tác động đến icon nữa**: file PNG trong thư mục `ios` mới là thứ được gửi cho Apple.

Kiểm tra từ thư mục gốc của dự án:

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

Nếu lệnh trả về `yes` cho icon 1024, hãy thay file đó bằng phiên bản không trong suốt, giữ nguyên tên. Nếu bạn chưa từng sửa tay phần native, bạn cũng có thể xóa thư mục `ios` và thêm nó vào `.gitignore`: EAS sẽ tạo lại nó ở mỗi lần build. Với Solys, TradaZen và Nolera, thư mục này được git bỏ qua.

## Định dạng iOS 26: Icon Composer

Icon Composer là công cụ của Apple cho icon Liquid Glass của iOS 26. Nó tạo ra một file `.icon` duy nhất gồm nhiều layer. Theo [hướng dẫn của Apple về Icon Composer](https://developer.apple.com/documentation/xcode/creating-your-app-icon-using-icon-composer), Xcode cũng lấy từ đó ra ảnh cho các phiên bản iOS cũ hơn.

Expo hỗ trợ định dạng này từ SDK 54. Bạn khai báo thư mục dưới dạng chuỗi, không bao giờ đặt trong object biến thể:

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

Trong trường hợp này, prebuild sao chép thư mục mà không chỉnh sửa gì, và Xcode mới là bên tạo ra icon cuối cùng. Vì vậy bạn cần Xcode 26 trở lên, phiên bản có trong các image EAS gần đây, như mình giải thích trong bài về [ITMS-90725](https://devoria.fr/vi/blog/itms-90725-sdk-version-issue-expo).

Từ tháng 8 năm 2025, trên diễn đàn developer của Apple, nhiều topic báo lỗi ITMS-90717 với file `.icon`. Các nguyên nhân được nhắc đến: một layer PNG trong suốt, một layer lớn hơn canvas, một group có hiệu ứng Blur gần mép. Các cách lách được đề cập: tắt Blur, giữ nền đặc, hoặc quay về PNG. Các topic này không có bản sửa chính thức nào từ Apple, và lỗi vẫn còn được báo vào tháng 8 năm 2026.

[Quy tắc của Apple về icon](https://developer.apple.com/design/human-interface-guidelines/app-icons) cũng theo hướng đó: nếu bạn import một layer nền, nó phải phủ toàn bộ bề mặt và không trong suốt. Các app của mình vẫn dùng PNG, nên mình chưa thử Icon Composer trên production. **Nếu file `.icon` chặn việc gửi build, hãy chuyển `ios.icon` về PNG**: Expo sẽ làm phẳng nó, và icon của bạn sẽ qua được bước kiểm tra này.

## Kiểm tra icon trong build cuối cùng

Trong IPA, icon 1024 không phải là file PNG: Xcode biên dịch nó vào `Assets.car`. Tải IPA từ trang build trên expo.dev, rồi chạy:

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

Mỗi icon hiển thị một trường `Opaque`. Ngày 15 tháng 10 năm 2026, mình dùng `actool`, công cụ của Xcode, để biên dịch icon của Solys và icon thử có góc trong suốt. Cái đầu ra `"Opaque" : true`, cái thứ hai ra `"Opaque" : false`. Apple không có tài liệu về trường này: hãy coi nó là một dấu hiệu, không phải bước kiểm tra của Apple.

Một cái bẫy cần biết: **đừng dùng `sips` để kiểm tra các file PNG nhỏ nằm ở gốc app.** Xcode ghi chúng kèm kênh alpha, kể cả khi file gốc không trong suốt. Trong bài test với icon của Solys, `sips` trả về `yes` cho chúng.

## Các lỗi icon khác

| Mã         | Apple báo gì            | Hướng xử lý với Expo |
| ---------- | ----------------------- | -------------------- |
| ITMS-90717 | Icon 1024 bị trong suốt | Xuất không có alpha  |
| ITMS-90704 | Thiếu icon 1024         | Thiếu mục 1024       |
| ITMS-90022 | Thiếu icon iPhone       | Catalog chưa đủ      |
| ITMS-90023 | Thiếu icon iPad         | Catalog chưa đủ      |

Ba thông báo cuối chủ yếu xuất hiện vào năm 2017 và 2018, khi Xcode 9 thay đổi quy tắc về icon.

Với Expo, chúng đã trở nên hiếm. Prebuild chỉ ghi một icon universal 1024 duy nhất, và Xcode tạo ra các kích thước còn lại. Nếu không khai báo icon, Expo thậm chí tạo một hình vuông trắng để tránh lỗi khi gửi. **Nếu gặp một trong các lỗi này, hãy xem thư mục `ios` trong git**: file `Contents.json` của `AppIcon.appiconset` phải có một mục kích thước `1024x1024`, và file PNG mà mục đó trỏ đến phải tồn tại.

## Trước lần gửi tiếp theo

Sửa icon chỉ mất mười phút, nhưng mỗi lỗi lại tốn một lần build. Các bước kiểm tra tự động khác cũng đòi hỏi sự cẩn thận tương tự, như [ITMS-90683](https://devoria.fr/vi/blog/itms-90683-missing-purpose-string-expo) cho các câu xin quyền hay [ITMS-91053](https://devoria.fr/vi/blog/sua-loi-itms-91053-missing-api-declaration-expo) cho privacy manifest. Khi build đã được chấp nhận, hãy cài nó bằng [TestFlight](https://devoria.fr/vi/blog/testflight-kiem-thu-app-iphone) để xem icon trên màn hình chính của bạn.

Bị reviewer từ chối thì cần bình tĩnh nhìn lại hơn: quy trình nằm ở trang [app bị Apple từ chối](https://devoria.fr/vi/expertise/ung-dung-bi-apple-tu-choi), còn các lý do phổ biến nhất nằm trong bài [vì sao Apple từ chối app](https://devoria.fr/vi/blog/apple-tu-choi-app-5-ly-do-thuc-te).

Để kiểm tra hồ sơ trước khi gửi, [Review Kit](https://devoria.fr/vi/kits/app-review) gom checklist của mình và các skill Claude Code đọc lại dự án của bạn. Nếu việc gửi bị kẹt và bạn muốn có người xem giúp, [đặt một giờ với mình](https://devoria.fr/vi/coaching): chúng ta cùng xem lại dự án qua video call, trên màn hình của bạn. Còn nếu bạn đang chuẩn bị phát hành lần đầu, [làm bài chẩn đoán miễn phí](https://devoria.fr/vi/diagnostic): nó sắp xếp lại các bước theo đúng thứ tự và gửi bạn checklist chống bị Apple từ chối của mình.

## Câu hỏi thường gặp

### Vì sao Apple thấy kênh alpha trong khi icon của tôi không hề trong suốt?

Vì một file PNG có thể giữ kênh alpha ngay cả khi mọi pixel đều không trong suốt. Nhiều công cụ tự thêm kênh này khi xuất file. Kiểm tra bằng `sips -g hasAlpha`, rồi xuất lại icon không có kênh này.

### Có thể sửa ITMS-90717 bằng bản cập nhật từ xa không?

Không. Icon được biên dịch vào binary, trong `Assets.car`. Bản cập nhật từ xa chỉ thay đổi JavaScript và tài nguyên của app. Hãy sửa icon, build lại, rồi gửi lại.

### Icon tối có được trong suốt không?

Có. Apple yêu cầu nền trong suốt cho biến thể tối, và Expo giữ nguyên độ trong suốt của nó. Từ đó mình suy ra bước kiểm tra nhắm vào icon chính, icon của App Store: chính icon đó phải không trong suốt.

### Có cần bo góc icon iOS không?

Không. Hãy cung cấp một hình vuông đặc: iOS tự áp mask. Bo góc sẽ để lại pixel trong suốt ở các góc, đúng thứ mà bước kiểm tra này từ chối.

### Expo có hỗ trợ icon Icon Composer của iOS 26 không?

Có, từ SDK 54: khai báo đường dẫn thư mục `.icon` trong `ios.icon`, dưới dạng chuỗi. Prebuild sao chép nguyên trạng và Xcode 26 biên dịch nó. Nếu gặp ITMS-90717 với định dạng này, hãy kiểm tra các layer trong suốt và hiệu ứng Blur, hoặc tạm thời quay về PNG.


## Dự án của bạn

[Review Kit](https://devoria.fr/vi/kits/app-review): Checklist duyệt App Store của mình, các lần Apple từ chối đã sửa, checklist Google Play và ba skill Claude Code. 1.399.000 ₫.

[iOS & Android Kit](https://devoria.fr/vi/kits/ios): Tạo app iPhone và Android với Claude Code: code khởi đầu từ các app của mình, lộ trình đến tận store và tất cả các kit. 2.799.000 ₫.

[Chẩn đoán: điều gì ngăn bạn có app iPhone](https://devoria.fr/vi/diagnostic): 7 câu hỏi, 60 giây: bạn biết điều gì thật sự cản bạn đăng app iPhone, lộ trình 4 bước và kit phù hợp với bạn.