app端强制横屏必须修改原生配置，js层uni.setscreenorientation基本无效；ios和android需分别在manifest.json中正确配置orientation字段，并重新云打包或制作自定义基座才生效。
App端强制横屏必须改原生配置，JS层调用uni.setScreenOrientation基本无效
这不是你代码写错了，而是 iOS 和 Android 系统从 12+ 开始严格限制 Web 层对屏幕方向的控制权。uni.setScreenOrientation 在 iOS 真机上几乎不返回任何错误，但实际既不旋转也不报错；Android 上仅部分旧机型（targetSdkVersion ）可能成功，新机型普遍被系统拦截。
常见错误包括：
- 在
onLoad里调用 —— 必须放在onShow，因为用户切后台再回来时方向可能已变 - 没检查返回值 —— 它返回 Promise，但失败时是
{ result: 'fail', errMsg: 'not supported' }，不是 reject - 误以为配了
pages.json的pageOrientation: "landscape"就能生效 —— App 端完全忽略该字段
iOS 和 Android 原生配置必须分平台、分字段、分格式写
manifest.json 中的 app-plus.distribute.ios.orientation 和 app-plus.distribute.android.orientation 是两个独立字段，不能混用、不能省略、不能填错格式：
- iOS：必须是数组，且只接受
["landscape-primary", "landscape-secondary"]；填"landscape"或单个字符串会被直接忽略 - Android：必须是字符串
"landscape"，不能是数组，也不能加连字符或大小写变形 - 两者必须同时存在 —— 缺一不可，否则对应平台打包后仍为竖屏
注意：app-plus.distribute.ios.orientation 这类字段在新版 uni-app 已弃用，若你用的是 HBuilderX 4.20+ 或 CLI 3.8+，请确认 manifest.json 结构是否匹配当前版本文档。
改完必须重新云打包或制作自定义基座，真机调试“运行到手机”不会生效
这是最常被跳过的步骤。所有 manifest.json 修改仅在以下两种情况下生效：
- 使用 HBuilderX 执行「发行 → 原生App-云打包」生成新安装包
- 本地制作「自定义调试基座」并重新安装到手机
而「运行到手机」或「真机调试」走的是热更新通道，不触发原生层重建，所以无论你怎么改 manifest.json，真机上都看不到效果。很多开发者卡在这里反复改 JS/CSS，其实根本没走到生效路径。
Canvas、Camera、视频播放等场景要避开uni.getSystemInfo返回值陷阱
uni.getSystemInfoSync() 返回的 screenWidth/screenHeight 是设备物理方向下的尺寸，不是横屏后的可用视口尺寸。例如 iPhone 14 Pro 横屏时，screenWidth 仍是 876（竖屏宽度），而非实际显示的 1792。
正确做法：
- Canvas 初始化时，用
uni.getSystemInfoSync().windowWidth和windowHeight，它们反映当前屏幕朝向的实际布局区域 - Camera 组件预览方向错乱，本质是 EXIF Orientation 标签未被解析 —— 需在上传前用
uni.getImageInfo提取 orientation 并手动旋转 canvas - 视频全屏退出后方向不恢复？监听
plus.video.Player.onstatechanged，在state === 4（ended）时主动调用plus.screen.lockOrientation('portrait-primary')
真正麻烦的不是怎么写，而是每个环节都依赖上一步是否真正横屏 —— 如果原生配置漏一项，后面所有适配逻辑都会跑偏。
