Flutter iOS 啟動畫面與應用程式圖示是做什麼的？

經過實戰考驗的 Flutter 應用程式模式：在第一個畫面顯示原生啟動標誌，以及遵循 iOS「自訂」→ 預設 / 深色 / 透明 / 著色的主畫面圖示。

使用時機

冷啟動時在 Flutter 載入前出現空白/米白色畫面
需要根據系統外觀（而非應用程式內的 ThemeCubit）顯示淺色 + 深色啟動標誌
需要在 iOS 18+ 上提供深色 / 著色 / 透明應用程式圖示變體

不適用時機

僅需要 Android 啟動畫面或 Flutter 應用程式內建 SplashScreen
僅透過應用程式內建主題切換（HydratedBloc）改變主題 — 這不會影響 LaunchScreen 或 SpringBoard 圖示

關鍵規則（不可跳過）

啟動標誌必須是應用程式 bundle 中的鬆散 PNG 檔案，而不是 Asset Catalog 的 imageset。SplashBoard 在第一個快照時經常無法從 Assets.car 執行 UIImage imageNamed，導致 2-3 秒的空白畫面。
如果存在同名的鬆散檔案，請勿將 BrandLogo 放入 Assets.xcassets — 目錄會優先，導致載入失敗。
LaunchScreen 上的背景色必須在 storyboard 中明確指定為 sRGB。命名顏色（例如 LaunchBackground）經常無法在啟動快照中切換。
特徵變化鍵值為 userInterfaceStyle=dark（不是 interfaceStyle，也不是 luminosity=dark）。
切勿透過將獨立的 ibtool storyboardc 複製到已建置的 .app 中來驗證啟動 — 這會導致黑色閃爍。請務必使用 flutter build ios --simulator（或實體裝置），然後解除安裝並重新安裝。
新增深色/著色後，請勿執行 flutter_launcher_icons — 它會覆寫 Contents.json 並刪除外觀設定。
主畫面圖示遵循 iPhone 外觀 / 自訂，而非 Flutter 主題。透明衍生自著色；沒有獨立的透明槽位。

工作流程檢查清單

進度：
- [ ] 1. 產生淺色 + 深色啟動 PNG（@1x/@2x/@3x）
- [ ] 2. 複製到 ios/Runner/ 並加入「複製 Bundle 資源」（pbxproj）
- [ ] 3. 從 Assets.xcassets 中移除任何 BrandLogo*.imageset
- [ ] 4. 更新 LaunchScreen.storyboard（鬆散圖片名稱 + 明確顏色）
- [ ] 5. 可選：僅為 Main.storyboard / SceneDelegate 交接建立 LaunchBackground.colorset
- [ ] 6. 產生應用程式圖示深色 + 著色 1024（以及保留舊版項目時的主畫面尺寸）
- [ ] 7. 使用 luminosity dark + tinted 更新 AppIcon.appiconset/Contents.json
- [ ] 8. flutter build ios --simulator --debug
- [ ] 9. simctl uninstall + install；驗證啟動時間 < 0.5 秒，並檢查 Assets.car 中的圖示外觀

步驟 1 — 產生啟動標誌

使用 scripts/generate_launch_logos.py。

輸入：

具有深色工作室背景的來源標誌（典型為 assets/logo/logo.png）
淺色：去背黑色 → 保留雙色品牌顏色
深色：相同 Alpha 遮罩，實心金色 #E0B45D（或專案主色）
尺寸：400×363 @1x、800×727 @2x、1200×1090 @3x（根據您的標誌調整比例）

去背公式（如果存在，請比對 Flutter SplashLogo）：

alpha_out = min(255, 4 * (R + G + B), source_alpha)

將輸出檔案放入 ios/Runner/：

BrandLogo.png、[email protected]、[email protected]
BrandLogoNight.png、[email protected]、[email protected]

步驟 2 — Bundle 資源

在 ios/Runner.xcodeproj/project.pbxproj 中：

為全部六個 PNG 新增 PBXFileReference + PBXBuildFile
將它們列在 Runner 群組和複製 Bundle 資源中
lastKnownFileType = image.png；引用 @2x / @3x 路徑

如果存在，請刪除 ios/Runner/Assets.xcassets/BrandLogo.imageset 和 BrandLogoNight.imageset。

建置後，確認：

# BrandLogo 不得在 Assets.car 中；PNG 必須存在於 Runner.app 中
find build/ios/iphonesimulator/Runner.app -name 'BrandLogo*.png'
xcrun assetutil --info build/ios/iphonesimulator/Runner.app/Assets.car | grep -i BrandLogo || true

步驟 3 — LaunchScreen.storyboard

使用現代 IB 格式（toolsVersion ≥ 21701、useTraitCollections、功能「文件以 Xcode 8 格式儲存」）。

模式（完整範本：references/launch-storyboard.md）：

UIImageView contentMode="scaleAspectFit"，圖片 BrandLogo
變化：key="userInterfaceStyle=dark" image="BrandLogoNight"
寬度 ≈ 父視圖的 0.28–0.40（從 ~0.32 開始）；高度 = 寬度 × 標誌比例
置中 X/Y 約束
淺色背景明確 sRGB（例如米白色 #FFFCF7）
深色背景變化明確 sRGB（例如 #17120E）
<resources> 必須宣告兩個圖片名稱及內在尺寸

Info.plist：UILaunchStoryboardName = LaunchScreen。

步驟 4 — Flutter 交接（可選但建議）

防止 Flutter 接管時出現白色閃爍：

LaunchBackground.colorset 包含淺色 + 深色亮度（適用於非啟動 UI）
Main.storyboard VC 背景 → 命名為 LaunchBackground
SceneDelegate / 自訂 FlutterViewController：在 viewDidLoad / viewDidLayoutSubviews 中從 UIColor(named: "LaunchBackground") 設定 view.backgroundColor 和 window.backgroundColor

步驟 5 — 應用程式圖示外觀（iOS 18+）

從 1024 行銷圖示（奶油色背景 + 標誌）使用 scripts/generate_app_icon_variants.py 產生。

外觀	圖稿
預設（任意）	現有淺色圖示
深色	深色底板上的金色標誌（`#17120E`）或根據 Apple HIG 使用透明背景
著色	灰階：黑色底板上的白色/灰色標誌（系統套用著色）
透明	自動從著色衍生 — 無需 Contents.json 項目

更新 AppIcon.appiconset/Contents.json — 請參閱 references/appicon-contents.md。

偏好使用包含以下內容的通用 1024 單一尺寸項目：

"appearances": [{ "appearance": "luminosity", "value": "dark" }]
"appearances": [{ "appearance": "luminosity", "value": "tinted" }]

如果專案仍在使用舊版 iPhone 項目，請保留每個尺寸的項目；至少為 60pt @2x/@3x 和行銷用 1024 新增深色/著色。

驗證：

xcrun actool ios/Runner/Assets.xcassets --compile /tmp/icons \
  --platform iphonesimulator --minimum-deployment-target 15.0 \
  --app-icon AppIcon --output-partial-info-plist /tmp/icon-partial.plist
xcrun assetutil --info /tmp/icons/Assets.car | grep -E 'UIAppearanceDark|ISAppearanceTintable'

建置後的應用程式應列出帶有 UIAppearanceDark 和 ISAppearanceTintable 的 AppIcon。

步驟 6 — 在模擬器上驗證

flutter build ios --simulator --debug
xcrun simctl uninstall booted <bundle.id>
xcrun simctl install booted build/ios/iphonesimulator/Runner.app
# 啟動：預期約 0.4–0.5 秒內顯示標誌（而非持續數秒的空白）
# 圖示：自訂 → 深色 / 著色；可能需刪除並重新安裝才能更新 SpringBoard 快取

sandboxed 代理環境中需要 simctl 的完整權限。

請勿 rm -rf SplashBoard 快取；解除安裝 + 重新安裝即可清除啟動快照。

品牌預設值（可依專案覆寫）

Token	預設值
淺色啟動背景	`#FFFCF7`
深色啟動背景	`#17120E`
深色標誌金色	`#E0B45D`
啟動標誌寬度	螢幕的 32%
深色圖示底板	`#17120E`

當專案使用不同品牌色時，請詢問使用者品牌十六進位值。

其他資源

Storyboard XML 範本：references/launch-storyboard.md
AppIcon Contents.json 形狀：references/appicon-contents.md
啟動標誌腳本：scripts/generate_launch_logos.py
圖示變體腳本：scripts/generate_app_icon_variants.py

Flutter iOS 啟動畫面與應用程式圖示