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

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

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:

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:

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

Theo tài liệu ImageMagick, -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: 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, 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 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:

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, 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ể:

{
  "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.

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

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 cho các câu xin quyền hay ITMS-91053 cho privacy manifest. Khi build đã được chấp nhận, hãy cài nó bằng TestFlight để 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, còn các lý do phổ biến nhất nằm trong bài vì sao Apple từ chối app.

Để kiểm tra hồ sơ trước khi gửi, Review Kit 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: 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í: 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.