支持 16 KB 的页面大小

16 KB Google Play 兼容性要求
自 2025 年 11 月 1 日起,提交到 Google Play 且以 Android 15 或更高版本为目标平台的所有新应用和现有应用更新都必须在 64 位设备上支持 16 KB 页面大小。

从历史上看,Android 仅支持 4 KB 内存页面大小,这优化了系统内存性能,以适应 Android 设备通常拥有的平均总内存量。从 Android 15 开始,AOSP 支持配置为使用 16 KB 页面大小的设备(16 KB 设备)。如果您的应用直接或通过 SDK 间接使用任何 NDK 库,则需要重新构建应用,才能在这些 16 KB 设备上运行。

随着设备制造商不断制造出具有更大物理内存 (RAM) 的设备,许多此类设备将采用 16 KB(最终甚至更大)的页面大小来优化设备性能。添加对 16 KB 页面大小设备的支持,可让您的应用在这些设备上运行,并帮助您的应用受益于相关的性能改进。如果不重新编译,应用将无法在未来 Android 版本的 16 KB 设备上运行。

为帮助您为应用添加支持,我们提供了相关指南,介绍了如何检查应用是否受到影响、如何重新构建应用(如果适用),以及如何使用模拟器(包括 Android 模拟器的 Android 15 系统映像)在 16 KB 环境中测试应用

优势和性能提升

配置为使用 16 KB 页面大小的设备平均会使用略多一些的内存,但系统和应用的性能也会得到各种提升:

  • 缩短了系统内存压力时的应用启动时间:平均降低了 3.16%;对于我们测试的某些应用而言,改进幅度更大(最高可达 30%)
  • 应用启动期间的功耗降低:平均降低了 4.56%
  • 相机启动更快:热启动速度平均提高了 4.48%,冷启动速度平均提高了 6.60%
  • 缩短了系统启动时间:平均缩短了 8%(约 950 毫秒)

这些改进基于我们的初始测试,实际设备上的结果可能会有所不同。随着测试的继续进行,我们将进一步分析应用的潜在收益。

检查您的应用是否受到影响

如果您的应用使用了任何原生代码,则应重新构建应用,使其支持 16 KB 设备。如果您不确定自己的应用是否使用了原生代码,可以使用 APK 分析器来确定是否存在任何原生代码,然后检查您找到的任何共享库的 ELF 段对齐情况。Android Studio 还提供了一些功能,可帮助您自动检测对齐问题

如果您的应用仅使用以 Java 或 Kotlin 编程语言编写的代码(包括所有库或 SDK),则该应用已支持 16 KB 设备。不过,我们建议您在 16 KB 环境中测试应用,以验证应用行为是否出现意外的回归。

您的应用是否使用了原生代码?

如果您的应用符合以下任一情况,则表明其使用了原生代码:

  • 您的应用使用了任何 C/C++(原生)代码。如果您的应用使用了 Android NDK,则表明您的应用使用了原生代码。
  • 您的应用与使用这些库的任何第三方原生库或依赖项(例如 SDK)相关联。
  • 您的应用是通过使用设备上的原生库的第三方应用构建程序构建而成。

使用 APK 分析器识别原生库

APK 分析器是一款可用于对所构建的 APK 进行各方面评估的工具。如需检查您的应用是否使用了原生代码(无论是否兼容 16 KB),请执行以下操作:

  1. 打开 Android Studio,然后依次点击 File > Open 并选择任意项目。
  2. 在菜单栏中,依次点击 Build > Analyze APK...

    用于启动 APK 分析器的 Studio Build 菜单选项
  3. 选择要分析的 APK。

  4. 查看 lib 文件夹,其中会托管共享对象 (.so) 文件(如有)。如果存在任何共享对象文件,则表明您的应用使用了原生代码。对齐列会针对存在对齐问题的任何文件显示警告消息。如果没有共享对象文件或没有 lib 文件夹,则表示您的应用未使用原生代码。

    显示存在共享对象文件的 APK 分析器视图

通过自动检查检测对齐问题

如果预构建的库或 APK 不符合 16 KB 的要求,Android Studio 会主动发出警告。使用 APK 分析器工具查看哪些库需要更新,或者是否需要进行任何代码更改。

有关项目对齐问题的 Studio 警告通知

Android Studio 中的 Lint 还会突出显示未按 16 KB 对齐的原生库。

Studio linter 针对未对齐的原生库发出警告

检查共享库的 ELF 段的对齐情况

对于任何共享库,请验证共享库的 ELF 段是否使用 16 KB ELF 对齐方式正确对齐。如果您是在 Linux 或 macOS 上进行开发,则可以使用 check_elf_alignment.sh 脚本,如下一部分中所述。您还可以直接使用命令行工具

使用 check_elf_alignment.sh 脚本(Linux 或 macOS)

请按照以下步骤使用 check_elf_alignment.sh 脚本检查 ELF 段的对齐情况:

  1. check_elf_alignment.sh 脚本保存到文件中。

  2. 对应用的 APK 文件运行脚本:

    check_elf_alignment.sh APK_NAME.apk
    

    该脚本会针对所有 arm64-v8a 共享库输出 ALIGNEDUNALIGNED

  3. 如果任何 arm64-v8ax86_64 共享库是 UNALIGNED,您需要更新这些库的打包,然后重新编译应用,并按照本部分中的步骤重新测试。

直接使用命令行工具

请按照以下步骤直接使用命令行工具检查 ELF 段的对齐情况:

  1. 确保使用 Android Studio 中的 SDK 管理器sdkmanager 命令行工具安装 Android SDK Build-Tools 版本 35.0.0 或更高版本以及 Android NDK。
  2. 提取应用的 APK 文件:

    Linux 或 macOS

    unzip APK_NAME.apk -d /tmp/my_apk_out
    

    Windows (PowerShell)

    Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
    
  3. 在您将 APK 文件提取到的临时目录中,检查 lib 目录的内容,看看是否有共享对象 (.so) 文件。这些是您在使用 APK 分析器识别原生库时看到的相同共享对象文件。对每个共享对象文件运行以下命令:

    Linux 或 macOS

    SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD
    

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"
    

    其中,SDK_ROOT_LOCATION 是您安装 Android SDK 的目录的路径,SHARED_OBJECT_FILE 是您要检查的共享对象文件的名称,NDK_VERSION 是您已安装的 Android NDK 的版本(例如 28.0.12433566)。对于您检查的每个文件,输出结果将类似于以下内容:

    LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
    LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
    LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14
    
  4. 检查输出行,确保负载段的值不小于 2**14。如果任何加载段的值为 2**132**12 或更低,您需要更新这些库的封装,然后按照本部分中的步骤重新编译应用并重新测试。

  5. 接下来,对应用的 APK 文件运行 zipalign 命令行工具:

    Linux 或 macOS

    SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk
    

    Windows (PowerShell)

    SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk
    

    其中,SDK_ROOT_LOCATION 是您安装 Android SDK 的目录的路径,APK_NAME 是您应用的 APK 文件的名称。如果所有共享库都正确对齐,则输出的最后一行将显示“验证成功”。

    如果验证失败,则需要重新对齐一些共享库,因此您需要更新这些库的封装,然后重新编译应用,并按照本部分中的步骤重新测试。

构建支持 16 KB 设备的 Android 应用

如果您的应用使用原生代码,请完成以下各部分中列出的步骤,以确保您的应用支持 16 KB 设备:

  1. 更新共享库的封装
  2. 使用 16 KB ELF 对齐方式编译应用
  3. 修复代码并解决运行时问题
  4. 检查 SDK 是否支持 16 KB

更新共享库的打包方式

我们建议您升级到 AGP 8.5.1 版或更高版本,并使用未压缩的共享库。

AGP 版本 8.5.1 或更高版本

对于随附未压缩共享库的应用,16 KB 设备要求这些共享库在 16 KB ZIP 对齐边界上对齐。为此,您需要升级到 Android Gradle 插件 (AGP) 版本 8.5.1 或更高版本。如需详细了解升级流程,请参阅 Android Gradle 插件升级助理部分。

AGP 版本 8.5 或更低版本

如果您无法将 AGP 升级到 8.5.1 版或更高版本,则可以改用压缩共享库。更新 Gradle 配置,以便 Gradle 在打包应用时压缩共享库,从而避免因共享库未对齐而导致的应用安装问题。

Groovy

build.gradle 文件中,添加以下选项:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

Kotlin

build.gradle.kts 文件中,添加以下选项:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

使用 16 KB ELF 对齐方式编译应用

16 KB 设备要求共享库的 ELF 段使用 16 KB ELF 对齐方式正确对齐,以便您的应用能够运行。

对于游戏开发者,如果您的游戏基于 Unity 游戏引擎运行,请参阅 Unity 指南。如果您的游戏基于 Unreal 游戏引擎运行,请参阅 Unreal 指南。对于原生游戏引擎,请继续阅读本指南。

如需使用 16 KB ELF 对齐方式编译应用,请根据您使用的 Android NDK 版本完成以下部分中的步骤。

Android NDK r28 及更高版本

NDK 版本 r28 及更高版本默认编译为 16 KB 对齐。

Android NDK r27

为了支持使用 Android NDK 版本 r27 及更高版本编译 16 KB 对齐的共享库,您需要按如下方式更新 ndk-buildbuild.gradlebuild.gradle.kts 或链接器标志:

ndk-build

Application.mk 中:

APP_SUPPORT_FLEXIBLE_PAGE_SIZES := true

Groovy

build.gradle 文件中,设置实参 -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

Kotlin

build.gradle.kts 文件中,设置实参 -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
      }
    }
  }
}

其他构建系统

指定以下链接器标志:

-Wl,-z,max-page-size=16384

Android NDK r26 及更低版本

如需支持使用 Android NDK 版本 r26 或更低版本编译 16 KB 对齐的共享库,您需要按如下方式更新 ndk-buildcmake 配置:

ndk-build

更新 Android.mk 以启用 16 KB ELF 对齐:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"

CMake

更新 CMakeLists.txt 以启用 16 KB ELF 对齐:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")

Android NDK r22 及更低版本

除了 NDK r26 及更低版本中所述的步骤之外,如果您使用的是 NDK r22 或更低版本,还必须设置 common-page-size=16384。由于 GNU ldLLVM lld 链接器的早期版本存在 bug,因此需要设置 common-page-size=16384。不过,我们强烈建议您将工具更新到较新版本,以完全避免这些 bug。

如需使用 Android NDK 版本 r22 或更低版本编译 16 KB 兼容的共享库,请按如下方式更新 ndk-buildcmake 配置:

ndk-build

更新 Android.mk 以构建 16 KB 兼容的 ELF:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"
LOCAL_LDFLAGS += "-Wl,-z,common-page-size=16384"

CMake

更新 CMakeLists.txt 以构建 16 KB 兼容的 ELF:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")
target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,common-page-size=16384")

修复代码并解决运行时问题

即使您的应用已对齐到 16 KB,如果代码中的某些位置假定设备使用了特定的页面大小,您的应用仍可能会遇到错误。为避免这种情况,请完成以下步骤:

  1. 移除代码逻辑中引用 PAGE_SIZE 常量或假设设备页面大小为 4 KB (4096) 的任何硬编码依赖项。

    请改用 getpagesize()sysconf(_SC_PAGESIZE)

  2. 查找 mmap() 的用法以及需要页对齐实参的其他 API,并在必要时替换为替代方案。

在某些情况下,如果您的应用使用 PAGE_SIZE 作为与底层内存页大小无关的便捷值,那么在 16 KB 模式下使用时,这不会导致应用崩溃。不过,如果使用 mmap 将此值传递给内核,而不使用 MAP_FIXED,内核仍会使用整个页面,从而浪费一些内存。出于这些原因,在 NDK r27 及更高版本上启用 16 KB 模式时,PAGE_SIZE 是未定义的。

如果您的应用以这种方式使用 PAGE_SIZE,并且从不直接将此值传递给内核,那么请创建一个具有新名称的新变量,以反映它用于其他目的,而不是反映真实的内存页,而不是使用 PAGE_SIZE

检查 SDK 是否支持 16 KB

许多 SDK 都与 16 KB 页面大小兼容,尤其是当您自行构建这些 SDK 或获取最新的预构建版本时。不过,由于某些 SDK 预构建版本或 SDK 版本与 16 KB 不兼容,您应查看每个 SDK 提供商的网站,以确定哪个版本可与 16 KB 搭配使用。

在 16 KB 环境中测试应用

构建支持 16 KB 设备的 app 后,您需要在 16 KB 环境中测试该 app,看看它是否出现任何回归问题。为此,请按以下步骤操作:

  1. 设置 Android 15 SDK

  2. 设置以下测试环境之一:

  3. 启动测试设备,然后运行以下命令,验证该设备是否使用 16 KB 环境:

    adb shell getconf PAGE_SIZE
    

    该命令应返回 16384 的值。

  4. 运行以下 zipalign 命令,验证您的应用是否按 16 KB 边界对齐,其中 APK_NAME 是应用 APK 文件的名称:

    zipalign -c -P 16 -v 4 APK_NAME.apk
    
  5. 全面测试您的应用,重点关注可能受到更改引用特定页面大小的代码实例影响的任何方面。

使用基于 16 KB 的 Android 15 系统映像设置 Android 模拟器

如需使用 Android 模拟器设置 16 KB 环境,请按以下步骤操作:

  1. 基于 16 KB 的 Android 15 模拟器系统映像与 Android Studio Jellyfish | 2023.3.1 或更高版本兼容。不过,为了在处理 16 KB 设备时获得最佳体验,请使用 Android Studio Ladybug | 2024.2.1 或更高版本。

    我们一直在努力开发新功能,因此建议您在有更新版本或 最新预览版的 Android Studio 时下载。

    请注意,您可以保留已安装的现有 Android Studio 版本,因为您可以并行安装多个版本

  2. 在 Android Studio 中,依次点击 Tools > SDK Manager

  3. SDK Platforms 标签页中,勾选 Show Package Details,然后展开 Android VanillaIceCream 或更高版本部分,并根据要创建的虚拟设备选择以下一个或两个模拟器系统映像:

    • Google APIs Experimental 16 KB Page Size ARM 64 v8a 系统映像
    • Google APIs 实验性 16 KB 页面大小 Intel x86_64 Atom 系统映像
    使用 Android Studio 中的 SDK 管理器下载 16 KB 模拟器系统映像
  4. 点击应用 > 确定,下载所选的系统映像。

  5. 按照步骤设置 Android 15 的虚拟设备,并在系统提示选择系统映像时,选择您下载的 16 KB 系统映像。如果系统未自动推荐,您可以在其他映像标签页中找到 16 KB 系统映像。

    在“其他映像”标签页中找到 16 KB 模拟器映像

针对某些模拟器版本和系统映像的额外步骤

对于 Android 模拟器版本 35.1.5 到 35.1.20,以及 SDK 管理器中提供的 Android 15.0 16 KB 页面大小系统映像的修订版 4 之前,若要在 x86_64 系统上模拟 16 KB 环境,您还需要完成以下步骤。在版本 35.1.21 之后,以及在 Android 15.0 16 KB 页面大小系统映像的修订版 4 或更高版本中,无需执行这些步骤。

  1. 在设备管理器中,点击 16 KB 映像旁边的 3 点状图标,然后点击在磁盘上显示
  2. 在此文件夹中,找到 config.ini 文件。
  3. 将以下行添加到 config.ini 文件中,然后保存更改:

    kernel.parameters = androidboot.page_shift=14
    
  4. 如需验证更改,请运行以下命令,该命令应返回 16384

    adb shell getconf PAGE_SIZE
    

启动模拟器

完成 Android 模拟器和虚拟设备的设置后,从目标设备菜单从命令行启动模拟器。

使用开发者选项在设备上启用 16 KB 模式

切换以 16KB 页面大小启动设备开发者选项,以在 16 KB 模式下启动设备。

从 Android 15 QPR1 开始,您可以使用某些设备上提供的开发者选项,以 16 KB 模式启动设备并执行设备端测试。在使用开发者选项之前,请依次前往设置 > 系统 > 软件更新,并应用所有可用的更新。

此开发者选项适用于以下设备:

  • Pixel 8 和 8 Pro(搭载 Android 15 QPR1 或更高版本)

    警告:由于 Android 15 QPR2 Beta 3 存在已知问题,在 Pixel 8 设备上安装 Android 15 QPR2 Beta 3 并以 16 KB 模式启动设备后,触摸屏无法正常工作。此问题不会影响 Pixel 8 Pro 设备。

  • Pixel 8a(搭载 Android 15 QPR1 或更高版本)

    警告:由于 Android 15 QPR2 Beta 3 存在已知问题,在 Pixel 8a 设备上安装 Android 15 QPR2 Beta 3 并以 16 KB 模式启动设备后,触摸屏无法正常工作。

  • Pixel 9、9 Pro 和 9 Pro XL(搭载 Android 15 QPR2 Beta 2 或更高版本)

Google Play 兼容性要求

随着设备制造商为设备配备更多 RAM 以优化性能,许多制造商将采用更大的页面大小(例如 16 KB)。为了迎接这些即将推出的设备,Google Play 推出了一项新的兼容性要求:自 2025 年 11 月 1 日起,提交到 Google Play 且以搭载 Android 15(API 级别 35)及更高版本的设备为目标平台的所有新应用和现有应用更新都必须支持 16 KB 页面大小。

如需详细了解此兼容性要求,请参阅这篇博文