博客

Play 管理中心 android.hardware.screen.portrait 报错解决

解决 Play 管理中心送审时「在声明中将硬件功能标记为必需」及 android.hardware.screen.portrait(Android XR)拦截报错。

在 Google Play 管理中心(Play Console)里,明明 .aab 在创建发布版本和预览并确认两步都顺利通过,工程里的竖屏代码也大半年没动过;可一到发布概览准备把新版本送审(关闭自管式发布模式或手动提交更改时),尚未提交送审的更改右侧的提交 1 项更改以供审核却变成了灰色不可点状态,下面横着一条刺眼的深红色提示——发现了 1 个问题:

Google Play 管理中心「发布概览」页面,右上角「提交 1 项更改以供审核」变灰,下方出现深红色「发现了 1 个问题」横幅

点开右侧的查看问题,弹出的提示框措辞非常唬人:

发现了 1 个问题

我们发现了一些常见问题,导致您的应用无法送审。您必须先解决这些问题,然后才能将更改送审。

在声明中将硬件功能标记为必需,导致您的应用分发范围受限

您的应用声明了对硬件功能的要求,但部分设备并不支持这些功能。由于以下硬件功能不受支持,使用这些设备的用户无法安装您的应用:

android.hardware.screen.portrait 会影响 手机、平板电脑、桌面设备和Android XR 用户

如需扩大应用的分发范围,请在应用清单中将非必需的硬件功能标记为可选。

Play 管理中心「发现了 1 个问题」弹窗,显示 android.hardware.screen.portrait 会影响手机、平板电脑、桌面设备和 Android XR 用户,底部带有「了解详情」与「仍然继续」

下面直接讲清楚三件事:这次已经传上去的包怎么 2 秒钟直接送审(不用改代码重打包)、为什么以前发版从来没报过、以及下个版本怎么在 AndroidManifest.xml 里加一行彻底消掉它。

1本次已传包最快处理:直接点「仍然继续」(不用重打包)

虽然弹窗开头写着「您必须先解决这些问题,然后才能将更改送审」,但这次你完全不需要舍弃版本或重新打包。

往 Play 管理中心上传过的 .aab 一旦入库,它的整数 versionCode 就被永久占用了——如果为了这条提示现在回去改代码,就得把 versionCode 再加 1(比如从 33 升到 34),重新走一遍打包和内部测试验证,白白耽误发版时间。

直接按下面三步在后台放行即可:

  1. 在发现了 1 个问题弹窗左下角,点击了解详情旁边的仍然继续(Proceed anyway)。
  2. 这时不会立刻提交,而是会弹出第二层确认框忽略此问题(请告诉我们您希望忽略此问题的原因)。勾选任意一项符合情况的原因——比如勾选我已计划解决此问题或发布这些更改内容比解决此问题更为重要——右下原本置灰的忽略问题按钮就会亮起,点击忽略问题:

Play 管理中心「忽略此问题」二次确认框,勾选「我已计划解决此问题」等原因后即可点击右下角「忽略问题」

  1. 回到发布概览页面后,原本灰掉的提交 1 项更改以供审核就会恢复可点击状态,再点它即可将当前 .aab 正常送审。

忽略它会影响过审或普通手机用户吗?不会。正如弹窗下方「这样做会有什么影响?」所写,版本会照常送审,普通安卓手机和支持竖屏的平板都能正常安装更新;只是在下次修改清单前,Google Play 会继续对不支持竖屏模式的纯横屏设备(如部分桌面端环境、车载屏和 Android XR 头显)隐藏安装入口,并在后续发版时再次提醒你。

2为什么大半年没改过的代码,突然报这个错?

很多开发者搜遍整个工程都找不到 android.hardware.screen.portrait 这串字符,原因出在后台新检查和构建工具隐式注入这两件事撞在了一起:

  1. Google 新增的大屏与 Android XR 送审前检查:配合 Android 16(targetSdk 36)的大屏自适应规范,Google Play 近期在发布概览上线了这项设备分发范围检查,目的是防止普通手机应用无意间把 ChromeOS / 桌面窗口模式、固定横屏平板以及 Android XR 头显(以空间浮动窗口运行 2D 应用)挡在门外。
  2. screenOrientation 触发了 AAPT2 的隐式硬件要求:只要最终合并出的 AndroidManifest.xml 里,有任意一个 <activity> 设置了固定竖屏(如 android:screenOrientation="portrait"、sensorPortrait 或 userPortrait),Android 构建工具 AAPT2 就会在打包时自动往清单里隐式塞入一条必需硬件声明:
<!-- 只要任意 Activity 锁了 portrait,AAPT2 编译时就会自动隐式注入: -->
<uses-feature
    android:name="android.hardware.screen.portrait"
    android:required="true" />

哪怕你自己的 MainActivity 没写死竖屏,Expo 项目 app.json 默认自带的 "orientation": "portrait",或者某个第三方扫码、相机、支付 SDK 内部的 <activity> 写了竖屏锁定,合并清单后都会触发一模一样的提示。

3下个版本一劳永逸的改法(AndroidManifest.xml)

等下次正常发新版本时,根据你的界面设计二选一即可:

方案 A:保留手机竖屏锁定,把竖屏硬件要求改成「可选」(最省事)

如果应用就是按手机竖屏设计的、暂时没打算重做横屏布局,原有的 android:screenOrientation="portrait" 不用删,只需在 AndroidManifest.xml 的 <manifest> 根节点下(<application> 上方)显式加一行覆盖声明:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-feature
        android:name="android.hardware.screen.portrait"
        android:required="false" />

    <application
        android:label="@string/app_name"
        ...>
  • 普通手机(最小宽度 < 600dp)依然保持竖屏锁定不变。
  • Google Play 读到显式的 android:required="false" 后,不再把物理竖屏当成硬性安装门槛,桌面端、横屏平板和 Android XR 空间窗口都能正常安装,发布概览里的红色拦截也会彻底消失。

如果第三方 SDK 显式写死了 required="true":万一某个第三方 .aar 在它自己的清单里直接写了 <uses-feature android:name="android.hardware.screen.portrait" android:required="true" />,Gradle 合并清单时默认会让 true 覆盖 false。这时加上 tools:replace="android:required" 强制以你的配置为准即可:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <uses-feature
        android:name="android.hardware.screen.portrait"
        android:required="false"
        tools:replace="android:required" />

各开发框架具体改哪个文件

  • Android Studio / Flutter / React Native 裸工作流 / Capacitor:直接编辑 android/app/src/main/AndroidManifest.xml(单模块原生工程为 app/src/main/AndroidManifest.xml)。这行只改清单声明,不涉及业务代码与 R8 混淆规则;不过毕竟动了原生层清单,下次发版前建议先在内部测试跑一遍,并顺手看一眼应用在大屏或多窗口缩放下有没有按钮被裁切。
  • Expo(Managed Workflow / EAS Build):create-expo-app 生成的 app.json 默认就写着 "orientation": "portrait"。如果使用 Prebuild 或 EAS 云端打包,直接改 android/ 会被覆盖——界面已适配横竖屏的可以直接把 app.json 里的 "orientation" 改成 "default";想保留手机竖屏锁定的,在 app.config.js 里加一段简短的 withAndroidManifest 插件即可自动写入:
// app.config.js
const { withAndroidManifest } = require("expo/config-plugins");

module.exports = ({ config }) =>
  withAndroidManifest(config, (mod) => {
    const features = mod.modResults.manifest["uses-feature"] ?? [];
    const existing = features.find(
      (f) => f.$?.["android:name"] === "android.hardware.screen.portrait"
    );
    if (existing) {
      existing.$["android:required"] = "false";
    } else {
      features.push({
        $: {
          "android:name": "android.hardware.screen.portrait",
          "android:required": "false",
        },
      });
    }
    mod.modResults.manifest["uses-feature"] = features;
    return mod;
  });
  • Unity:如果游戏本身支持旋转,在 Project Settings > Player > Android > Resolution and Presentation 将 Default Orientation 设为 Auto Rotation;如果必须锁竖屏,在 Publishing Settings 勾选 Custom Main Manifest,然后在生成的 Assets/Plugins/Android/AndroidManifest.xml 中补上上面的 <uses-feature> 声明。

方案 B:界面本身支持自适应,直接移除固定竖屏属性

如果你的界面在横屏和分屏窗口下本来就排版正常(况且在 Android 16 / targetSdk 36 下,系统在最小宽度 ≥ 600dp 的平板与大屏设备上已经默认忽略固定方向锁),直接删掉 <activity> 上的 android:screenOrientation="portrait"(或把 Expo app.json 的 "orientation" 设为 "default"),AAPT2 自然就不会再隐式生成竖屏硬件要求。

4本地自检方法与同一个弹窗常抓的其他隐式硬件要求

下次打新包上传前,可以先在本地确认隐式要求确实已经解除:

  • 在 Android Studio 查看合并结果:打开 AndroidManifest.xml,切换到编辑器底部的 Merged Manifest 标签页,可以确认显式声明的 android:required="false" 已合并生效,并一眼揪出是哪个第三方库塞进了 screenOrientation 或 <uses-feature>(AAPT2 隐式推导的特征需用下方命令查看)。
  • 用 aapt2 命令行核对:对打出来的 release APK(或从 .aab 导出的通用 APK)执行 aapt2 dump badging app-release.apk,确认输出里的 android.hardware.screen.portrait 已经变成 uses-feature-not-required,而不是 uses-feature。

另外,同一个「在声明中将硬件功能标记为必需,导致您的应用分发范围受限」弹窗还会顺带拦截由敏感权限隐式触发的硬件门槛。如果弹窗里同时列出了下面几项,用完全相同的 android:required="false" 一并标为可选即可:

清单里声明的权限 AAPT2 默认隐式要求的硬件功能 在 AndroidManifest.xml 中补齐的覆盖写法
android.permission.CAMERA 同时要求 android.hardware.camera 和 android.hardware.camera.autofocus 两项都必须显式设为 android:required="false"(只改 camera 漏掉 autofocus,Chromebook、多数平板和仅带前置摄像头的设备依然无法安装)
android.permission.RECORD_AUDIO android.hardware.microphone <uses-feature android:name="android.hardware.microphone" android:required="false" />
CALL_PHONE / SEND_SMS android.hardware.telephony <uses-feature android:name="android.hardware.telephony" android:required="false" />(否则无蜂窝通话模块的 Wi-Fi 平板、桌面端与 XR 设备全部无法安装)

顺利送审之后,下一步是什么?

如果你是在前面的创建发布版本或预览并确认阶段遇到了其他报错——比如 16 KB 原生库对齐、AD_ID 广告 ID 声明冲突、版本代码重复,或是关于去混淆文件(R8)与调试符号的黄色警告——可以直接查 Play 管理中心上传 AAB 报错汇总:常见原因与解决办法。

对于正在跑封闭式测试的个人开发者账号,在发布概览点完送审、测试版本过审生效后,接下来就是整个上架流程最磨人的一关:必须招募至少 12 名测试人员参与您的封闭式测试至少 14 天(连续满 14 天),后台才会开放申请正式版发布权限——具体怎么算满 14 天见 12 名测试人员、14 天:「连续」到底是什么意思。

独立开发想找齐 12 台真实安卓设备并不容易:身边朋友不是用 iPhone 就是装完两天再也没打开过,去社区零散互测又经常遇到点了加入测试链接却不安装、或者半途卸载掉线的人。如果你也在凑这 12 名测试人员,可以试试 BetaLobby(完全免费,无付费套餐):16 位开发者通过组队模式共用一个 Google 群组互相测试 14 天,免截图自动核验真机安装,并用每日打卡把每天实际打开应用的记录稳稳留住。