我把蘑菇视频 iOS 的横竖屏切换踩坑点全列出来了：我反复确认了三次
蘑菇视频的横竖屏切换看似简单，但从用户体验到技术实现、从 App Store 政策到 iOS 多版本差异，能出问题的地方多得让人头疼。我把自己在多台 iPhone、不同 iOS 版本上反复复现过的坑都整理成这篇文章，少走弯路，少被“横屏黑洞”困住——我真的确认了三次，保证可靠。
测试前说明
- 测试环境覆盖多台 iPhone 与 iOS 版本（包含 iOS 15/16/17 等常见版本），用过原生播放器、WKWebView 嵌入页面与自定义 AVPlayer 三种实现方式。
- 以下内容既面向普通用户的排查步骤，也包含给开发者的修复建议。
常见踩坑点（按问题出现频率排序）及解决办法
1) 手机旋转被系统锁死（最常见的“低级错误”）
- 症状：无论怎么转屏，视频保持竖屏或横屏不动。
- 排查：拉下 Control Center 检查旋转锁定是否打开。
- 解决：提醒用户关闭旋转锁定；在产品说明或设置页加入提示图示。
2) 应用或视图控制器没声明支持的方向
- 症状：进入全屏播放或某个页面后强制某个方向，切回其他页面又变回去。
- 原因与修复：
- Info.plist 中的 Supported interface orientations 与实际页面不一致会导致问题。确认 Info.plist 支持的方向包含你想要的横屏/竖屏。
- 对于需要单独控制方向的 VC，重写 supportedInterfaceOrientations 与 preferredInterfaceOrientationForPresentation。
- 如果是模态展示的播放器，presentationStyle 要设为 fullScreen，否则系统可能不会按期望旋转。
3) 强制设置方向（UIDevice.setValue）带来的不稳定 & 审核风险
- 症状：通过 UIDevice.setValue 强制旋转偶尔失效，切换时动画不连贯，或怀疑会影响上架。
- 说明与建议：
- 这种方法短期可用但不是官方推荐做法，可能在不同 iOS 版本或未来被限制。
- 更稳妥的方式是通过 supportedInterfaceOrientations 与模态 VC 控制方向，或在 App 里设计用户可接受的交互流程（例如显式的「进入横屏播放」按钮）。
4) 全屏播放器与导航/状态栏冲突
- 症状：横屏后导航栏、状态栏没有隐藏或布局错位，控制栏覆盖视频。
- 排查与修复：
- AVPlayerViewController 的 modalPresentationStyle 设为 fullScreen，并确保 prefersStatusBarHidden 与 view controller 的状态栏配置一致。
- 使用 safeAreaInsets 考虑刘海和 home 指示器位置，避免控件被遮挡。
5) WKWebView / H5 视频在容器里不能正确旋转
- 症状：网页播放的视频在横屏时页面不跟着旋转，或旋转后 WebView 内元素位置错乱。
- 原因与处理：
- Web 内容本身无法直接控制宿主 App 的方向，宿主需要处理方向并通知或重布局 WebView。
- 在容器里监听设备方向变化，调用 evaluateJavaScript 告知页面重新布局；或者在切换方向时刷新 WebView 布局（避免频繁刷新导致闪烁）。
6) 约束（Auto Layout）和布局没适配方向切换
- 症状：切到横屏后控件跑位、重叠或超出屏幕。
- 处理建议：
- 使用相对 safe area 的约束而非固定像素。
- 在旋转回调中（viewWillLayoutSubviews / viewDidLayoutSubviews）调用 layoutIfNeeded 并配合动画调整约束优先级。
- 避免在主线程做大量计算导致旋转卡顿。
7) 视频本身的元数据导致旋转错误（录制或导入的视频）
- 症状：上传或播放的视频在播放器里方向不对（看起来被旋转了）。
- 原因与解决：
- 很多手机录制的视频带有 EXIF/transform 元数据，播放器是否识别这些影响显示方向。
- 上传前使用 AVAssetExportSession 重新导出并应用正确 transform，或在播放端根据 metadata 做旋转处理。
8) 播放器重建导致中断或闪烁
- 症状：每次切换方向播放器被销毁重建，导致重新缓冲或黑屏。
- 建议：
- 尽量保留单一播放器实例并只是调整其 layer/frame，而不是反复销毁和创建。
- 对于流媒体，优先使用能平滑调整尺寸的播放器组件（避免频繁 reset playerItem）。
9) iOS Scene / 多窗口与老代码的冲突
- 症状：引入 SceneDelegate 的项目在多窗口下方向行为不一致。
- 说明与对策：
- 新的 Scene 架构下，窗口级别控制方向更细粒度，确认各个 scene 的 window 和 rootViewController 的 supportedInterfaceOrientations 设置一致。
- 避免在 AppDelegate 里做全局 orientation 控制而忽略 SceneDelegate。
10) 第三方 SDK 或广告组件覆盖方向策略
- 症状：集成了第三方广告或播放器 SDK 后，横竖屏行为异常。
- 排查技巧：
- 逐个禁用第三方组件复测，查看是否有 SDK 覆盖了 supportedInterfaceOrientations 或弹出模态 VC。
- 查文档，按 SDK 推荐方式配置 orientation 权限或回调。
11) 手势冲突（ScrollView 与横屏手势）
- 症状：横屏手势或滑动手势与播放器的手势冲突，导致误触或方向切换手感差。
- 解决：
- 设置 gestureRecognizer.delegate，合理实现 shouldRecognizeSimultaneouslyWith。
- 在触控开始时临时禁用冲突手势，播放结束后恢复。
实战小贴士（开发者 / 产品都能用）
-
对开发者：
-
Info.plist、App 的全局方向与每个需要特别行为的 VC 都要对应配置，避免“哪里支持横屏哪里不支持”的不一致。
-
优先使用 AVPlayerViewController（系统层面更好地处理旋转、状态栏和控制器），必要时再做自定义控件。
-
在旋转回调里不要做重度计算，保持主线程轻量，避免卡顿。
-
对产品/运营：
-
在播放器页提供显式的“进入横屏/退出横屏”按钮，减少用户依赖系统旋转开关。
-
在常见机型和 iOS 版本上做回归用例，记录设备、系统版本和复现步骤，避免单机通过却线上报错频出。
-
对 Web 嵌入场景，写好前后端配合规范，比如容器如何通知页面尺寸变化、页面如何响应。
我的三次确认——为什么要反复测？ 第一遍是“能不能复现”，第二遍是“复现条件是什么”（是否和网络、机型、iOS 版本相关），第三遍是“修复后有没有副作用”。很多问题看起来修好了，但在极端机型或特殊场景下会冒头，三遍验证能把大多数边界情况踢出来。
快速检查清单（发布前最后一遍）
- Info.plist 的 supported orientations 是否完整？
- 关键页面的 supportedInterfaceOrientations、preferredInterfaceOrientationForPresentation 是否正确？
- 模态展示是否使用 fullScreen？
- 是否在多个 iOS 版本与多台真机上回归测试过？
- 第三方 SDK 有没有覆盖方向行为？
- 是否处理了刘海、安全区域、home 指示器等布局？
- 是否避免在旋转里做重计算导致卡顿？
