游戏 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。

设计整屏稿经 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；Studio 重导层级	程序 + 设计
点击偏移	多 Canvas / Camera UI / Scaler 嵌套	合并 Canvas 或统一射线相机	程序
换分辨率仅漂移	Anchor 全 fixed 未用 stretch	改 Anchor；见 进引擎第 6 项	程序
设计稿无安全区框	交稿缺 交稿自查第 7 项	设计补 notch/底条参考框；再导出	设计
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 是一回事吗？
不是。见 对比文。