iPhone Duo 适配实战（三）：上市日冲刺清单与六个实战陷阱

系列第一篇讲布局 API，第二篇讲铰链与多场景。今天是收官篇：iPhone Duo 上市日，你的冲刺清单和实战中真正会踩的坑。所有结论基于 Xcode 27.1 正式版（27A9275）与官方文档实证。

先说好消息：SDK 替你做了大半

iOS 27.1 SDK 内置了大部分自动适配：

TabView 的标签栏、工具栏自动迁移为竖向侧边栏
窗口默认edge-to-edge 全屏铺开
SwiftUI 直接告诉你折痕在哪（reserved regions）、开合到什么程度（onHingeChange）

你的主要工作是别挡路——以下是六个会”挡路”的实测陷阱。

陷阱一：一个 ToolbarItem 塞两个按钮

这是最常见也最隐蔽的坑。把多个按钮放进同一个 ToolbarItem，系统的侧边栏自动迁移会静默失败，你的工具栏停留在原地将就显示。

修法：拆开。

// ❌ 阻断自动适配
ToolbarItemGroup(placement: .primaryAction) {
  Button("分享") { }
  Button("收藏") { }
}

// ✅ 各自独立
ToolbarItem(placement: .primaryAction) { Button("分享") { } }
ToolbarItem(placement: .primaryAction) { Button("收藏") { } }

陷阱二：布局模式缓存（最坑，救命题）

Duo 会保留 App 首次安装时的布局模式。 你用新 SDK 重新构建、覆盖安装到模拟器/真机——界面上去”毫无变化”，让人误以为适配代码无效。

修法：每次换 SDK 测试 Duo 适配前，先删除 App 再全新安装。把这条写进团队的测试 SOP。

陷阱三：模拟器里 StandBy 与 App Extension 不可用

Xcode 27.1 的 Duo 模拟器运行时不支持 StandBy 和大多数 App Extension。如果你的 App 依赖 Widget/Intents 扩展做 Duo 联动验证，模拟器会给你假阴性——这部分只能等真机或用 TestFlight。

陷阱四：忘了外屏是「另一个 size class」

合盖态的外屏是独立屏幕、独立 size class。用 Previews 新增的 Display 分组直接预览副屏渲染，不用来回切换模拟器姿态：

Canvas Overrides → Display → 选择 Outer Display

陷阱五：截图规格与徽章

App Store Connect 已有 iPhone Duo 截图槽位（两种尺寸）。提交「Optimized for iPhone Duo」的 App 可获得徽章露出；2027 年 4 月起，Duo 截图成为提审硬性要求。现在补齐素材比明年抢着补便宜。

陷阱六：把折叠当 iPhone 大屏做

复盘官方六场 Tech Talks 的共同指向：Duo 的正确心智是 iPad 的多任务 + 全新姿态，不是大号 iPhone。ArrangementView（split/overlay）承担分栏、reserved regions 承担绕行、onHingeChange 承担交互——三件套之外的”自研布局计算”几乎都是过度设计。

上市日冲刺清单（按优先级）

Xcode 27.1 重编译，跑通全姿态模拟器（展开/书本/支架/合盖）
全局搜索 ToolbarItemGroup / 多按钮 ToolbarItem，逐一拆分
删 App 重装，验证侧边栏迁移与 edge-to-edge 生效
检查 NavigationSplitView 未嵌套进 ArrangementView（系列一篇禁忌）
补 Duo 截图两种尺寸，提交拿首发窗口与徽章
相机类 App：CameraCaptureAccessory 外屏配件（系列二篇）
记录首日真实设备崩溃（Organizer + MetricKit）

系列收官

三篇教程覆盖了 Duo 适配从布局到交互到发布的完整链路。上市后本站会跟进真机实测中发现的新问题——欢迎在评论区提交你的踩坑记录，精选后更新进本文。

详见Xcode 27.1 发布说明与官方 Tech Talks 系列。