遊戲 UI Safe Area 與真機驗收：程式排查順序與 Prefab 修正

最常見回饋是：Unity Editor Game 檢視裡沒問題，打包到長螢幕真機後 HUD 被瀏海吃掉，或按鈕看起來能點、實際點偏。 這不是「再調一下 Anchor」能蒙混過關——Safe Area 涉及 Canvas 根策略、全螢幕背景與內容層是否分離、執行時 safeArea 矩形是否與渠道一致，需要在 Editor 裡可重現的日誌 + 真機 smoke 一起驗收。

下文給出 失敗分類、Unity UGUI 排查順序、Prefab 修正原則、渠道/小遊戲差異注意點。設計稿交稿自查 第 7 項的安全區標註見文末「設計需配合什麼」；發布前清單第 1 項 的真機範圍本文展開執行細節，不重複 進引擎 MCP 清單 的 Raycast / 首次 Play 項。

Godot / Cocos： 對照 DisplayServer.get_display_safe_area() / 各引擎 SafeArea 元件與 Widget 邊距，排查順序與下文 Unity 步驟同構。

失敗判據（任一即未通過）： 主流程可讀 UI 或必填按鈕落在系統遮擋區（瀏海、Home 條、圓角螢幕角）；視覺與可點區域相對手指偏移明顯；僅 Editor 16:9 通過、目標長寬比真機未測；Release 包與 Dev 包 Safe Area 行為不一致且未在規格中說明。

---

先分類：裁切、偏移、還是僅背景

現象	優先懷疑	先做
視覺裁切（字/圖示進 notch）	內容層未 inset；根 Canvas 當全螢幕用	看 safeArea 與內容 Rect 是否相交
點擊偏移（看著點對、實際無效）	Canvas 縮放模式、多 Canvas、Camera 不一致	查 EventSystem 射線與 Canvas renderMode
僅背景被切、按鈕正常	全螢幕 Background 故意 bleed，內容已 inset	規格允許則 不算失敗
橫豎屏切換後錯位	未監聽 Screen.orientation / safeArea 變化	旋轉後重算 inset 或重佈局
僅某渠道包	渠道 SDK 改 safeArea 或解析度	該渠道包單獨 smoke，勿只測通用 Android

---

Unity UGUI：推薦排查順序（6 步）

1. 固定 reproduction 環境

• 記錄：機型、系統版本、包類型（Dev/Release）、豎橫屏、Game 檢視解析度。
• 發布前第 5 項：Dev 與 Release 各走一遍主 HUD。

2. 打日誌：safeArea 與參考解析度

在進主 UI 後列印（或臨時 OnGUI）：

• Screen.width / Screen.height
• Screen.safeArea（x, y, width, height）
• Display.cutouts（Android 11+ 若使用）

判讀： safeArea 比螢幕小 → 必須有內容 inset 策略；Editor 裡 safeArea 常等於全螢幕 → 不能以 Editor 日誌代替真機。

3. 查 Canvas 根與 Canvas Scaler

檢查	常見錯誤	修正方向
根 Canvas Render Mode	Screen Space 與 Camera 混用導致射線偏移	全 UI 統一一種模式
Canvas Scaler（Scale With Screen Size）	Reference Resolution 與專案豎屏基準不一致	對齊 進引擎清單 第 1 項約定
Match 寬/高	長螢幕下整體縮放錯、貼邊控件漂移	與策劃定 Match 策略，改 Prefab 非 Scene 臨時值
多 Canvas 排序	點擊落到下層	sortingOrder 與 Graphic Raycaster 目標一致

4. 分層：全螢幕背景 vs Safe 內容

推薦 Hierarchy（程式可在 Prefab 固化）：

Canvas
├── Background_FullBleed   （Anchor 全螢幕，可進 notch，無互動）
└── SafeRoot               （掛 Safe Area 腳本或按 safeArea 設 Padding）
    ├── HUD_Content
    └── Popups

• 使用 Unity Safe Area 元件（或專案自研：讀取 Screen.safeArea 設 RectTransform.offsetMin/Max）。
• 勿對需要點擊的按鈕使用全螢幕 stretch 且不做 inset。

設計整螢幕稿經 AI Studio 匯出時，若 Background 與 HUD 未分層，見 九宮格 / 結構化重匯 與 畫布 → Prefab 整樹修正。

5. 真機點擊抽測

• 主流程 3–5 個關鍵按鈕（開始、關閉、確認支付入口等）用同手指位置對比視覺中心。
• 偏移僅出現在某彈窗 → 查該 Prefab 是否嵌在不同 Canvas 下或 Scaler 被父節點重複縮放。

6. 寫回倉庫 Prefab

• 通過項必須落在 版本庫 Prefab，不是測試 Scene 覆蓋（對照 發布前第 6 項）。
• 改 Anchor 後跑一遍 多語言 smoke（長文案 + 長螢幕），避免 inset 後爆框。

---

渠道包 / 小遊戲

不綁定單一 SDK 版本，只列常見差異：

場景	注意點
原生 App	以 Screen.safeArea + 真機為準
部分小遊戲 / 快應用	容器提供 safeArea 或 systemInfo 與 Editor 模擬不一致
異形屏 Android	cutout 與 safeArea 可能不同
PC / Steam Deck 等	safeArea 常為全螢幕

原則： 抽象一層 ISafeAreaProvider（或專案等價物），App 與小遊戲注入不同實作，避免 HUD Prefab 裡寫死平台 #if。

---

回修路徑表

現象	最可能原因	建議動作	負責
真機裁切、Editor 正常	無 SafeRoot / 無 safeArea 驅動	Prefab 加分層 + Safe Area；真機複測	程式
全螢幕背景 OK、按鈕被切	按鈕掛在 Bleed 層下	移到 SafeRoot；AI Studio 重匯層級	程式 + 設計
點擊偏移	多 Canvas / Camera UI / Scaler 嵌套	合併 Canvas 或統一射線相機	程式
換解析度僅漂移	Anchor 全 fixed 未用 stretch	改 Anchor；見 進引擎第 6 項	程式
設計稿無安全區框	交稿缺 交稿自查第 7 項	設計補 notch/底條參考框；再匯出	設計
AI Studio 匯出整螢幕一體	背景與 HUD 未拆	原位拆分 後重匯	程式 + 設計

---

設計需配合什麼

修 Safe Area 仍需要稿面 「可互動區」與「可 bleed 背景」 分界：

設計交付	用途
目標解析度 + 安全區參考框（notch / Home 條）	對齊 Reference Resolution 與 inset 預期
全螢幕背景與 HUD 分層命名	Prefab Background_* / SafeRoot 對應
貼邊 Tab / 底欄是否在 safe 內	決定 Anchor 策略，避免「稿面貼邊、真機進 notch」

不要求設計師寫腳本；標註清晰可減少程式猜 inset 像素。

---

常見問題

Game 檢視選 iPhone 解析度算驗收嗎？
可作開發期冒煙；發布前仍須目標真機（發布前第 1 項）。Editor 的 safeArea 與裝置常不一致。

Safe Area 元件與手寫 offset 選哪個？
團隊統一即可。手寫時須在 safeArea 變化時（旋轉、分割畫面）重算；避免多處重複邏輯。

只改 Canvas Scaler 能修裁切嗎？
Scaler 管縮放比例，不替代 safeArea inset。裁切是內容矩形問題，Scaler 是整體比例問題。

MCP / Cursor 能代勞嗎？
適合批次改 Prefab 命名、掛 Safe Area 腳本、Play 模式抽測；safeArea 數值仍要以真機日誌為準。見 進引擎 + MCP 清單。

與多語言爆框同時出現？
先保證 SafeRoot 內佈局，再測 壓力語言；inset 會縮小可用寬，易觸發爆框。

VberAI Studio 與 Google AI Studio 是一回事嗎？
不是。見 對比文。