支持 16 KB 的页面大小

Historically, Android has only supported 4 KB memory page sizes, which has optimized system memory performance for the average amount of total memory that Android devices have typically had. Beginning with Android 15, AOSP supports devices that are configured to use a page size of 16 KB (16 KB devices). If your app uses any NDK libraries, either directly or indirectly through an SDK, then you will need to rebuild your app for it to work on these 16 KB devices.

As device manufacturers continue to build devices with larger amounts of physical memory (RAM), many of these devices will adopt 16 KB (and eventually greater) page sizes to optimize the device's performance. Adding support for 16 KB page size devices enables your app to run on these devices and helps your app benefit from the associated performance improvements. Without recompiling, apps might not work on 16 KB devices when they are productionized in future Android releases.

To help you add support for your app, we've provided guidance on how to check if your app is impacted, how to rebuild your app (if applicable), and how to test your app in a 16 KB environment using emulators (including Android 15 system images for the Android Emulator).

优势和性能提升

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

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

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

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

如果您的应用使用了任何原生代码，则应重新构建应用以支持 16 KB 设备。如果您不确定自己的应用是否使用了原生代码，可以使用 APK 分析器确定是否存在任何原生代码，然后检查您找到的任何共享库的 ELF 段对齐情况。

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

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

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

• 您的应用使用了任何 C/C++（原生）代码。如果您的应用使用 Android NDK，则表明您的应用使用了原生代码。
• 您的应用与使用这些库的任何第三方原生库或依赖项（例如 SDK）关联。
• 您的应用由使用设备端原生库的第三方应用构建程序构建而成。

使用 APK 分析器识别原生库

APK 分析器是一款可用于对所构建的 APK 进行各方面评估的工具。如需确定您的应用是否使用原生代码或库，请按以下步骤操作：

1. 打开 Android Studio，然后依次点击 File > Open，然后选择任意项目。

2. 在菜单栏中，依次点击 Build > Analyze APK...

   

3. 选择要分析的 APK。

4. 查看 lib 文件夹，其中会托管共享对象 (.so) 文件（如有）。如果存在任何共享对象文件，则表明您的应用使用了原生代码。如果没有共享对象文件或没有 lib 文件夹，则表示您的应用不使用原生代码。

   

检查共享库的 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 共享库输出 ALIGNED 或 UNALIGNED。

3. 如果任何 arm64-v8a 或 x86_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**13、2**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 设备的应用

如需支持 16 KB 设备，使用原生代码的应用应完成以下部分中列出的步骤。如果您更新到 AGP 8.5.1 或更高版本和 NDK r28 或更高版本，并使用与 16 KB 兼容的预构建依赖项，则应用默认与 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.3 到 8.5 中，应用默认采用 16 KB 对齐。不过，bundletool 默认不会对 APK 进行 zipalign 处理。因此，应用看似可以正常运行，但在 Play 中通过 bundle 构建时，无法安装。

如果您无法将 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 对齐方式正确对齐，才能运行应用。

注意： 如果您的应用未将原生库提取到文件系统（extractNativeLibs 设置为 false），您可能会发现在使用 16 KB ELF 对齐方式进行编译后，应用的二进制文件大小略有增加。Android 15 中对软件包管理器的优化可抵消因增加而产生的运行时开销。

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

重要提示： 如果您的应用使用了任何预构建的共享库，您还必须以相同的方式重新编译这些库，并将对齐到 16 KB 的库重新导入到您的应用中。

Android NDK r28 及更高版本

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

Android NDK r27

如需支持使用 Android NDK 版本 r27 及更高版本编译 16 KB 对齐的共享库，您需要更新 ndk-build、build.gradle、build.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-build 或 cmake 配置：

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")

重要提示： 即使您的应用动态链接到 NDK r26 及更低版本中的 C++ 标准库 (libc++_shared.so)（其中一些库未对齐到 16 KB），您仍然应更新此处所有其他库的对齐方式，并应更新代码以避免依赖于 PAGE_SIZE。为了在 16 KB 设备上使用较低版本的 NDK 进行测试，Android CI 上提供了 LTS NDK 版本 r23 和 r25 的 Canary 版本，以及 16 KB 对齐的 libc++_shared.so 库。无论如何，建议改用 Android NDK r27 或更高版本，以更新到 16 KB ELF 对齐版本的 C++ 标准库。否则，您的应用将无法在 16 KB 设备上安装。

如果您无法迁移到较新的 Android NDK，则可以更新应用，将 C++ 标准库静态编译到共享库中。如需详细了解如何静态关联到 C++ 标准库，请参阅 C++ 库支持部分，并务必阅读重要注意事项部分。

检查是否存在引用特定页面尺寸的代码实例

即使您的应用是 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 预构建或 SDK 版本不支持 16 KB，因此您应查看每个 SDK 提供商的网站，以确定应与 16 KB 搭配使用哪个版本。

在 16 KB 环境中测试应用

构建支持 16 KB 设备的应用后，您需要在 16 KB 环境中测试应用，以了解应用是否出现任何回归问题。为此，请按以下步骤操作：

1. 设置 Android 15 SDK。

2. 设置以下任一测试环境：

   • 使用基于 16 KB 的 Android 15 系统映像设置 Android 模拟器
   • 使用开发者选项在设备上启用 16 KB 模式
   • 在 ARM64 上使用页面大小为 16KB 的 Cuttlefish
   • 在 x86-64 上模拟页面大小为 16KB 的 Cuttlefish

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 模拟器

重要提示： 存在一个已知问题，会导致无法使用 LLDB 调试 16 KB 模拟器系统映像。NDK r27 RC 1 和 Android Studio Koala 功能更新 | 2024.1.2 Canary 5 中包含针对此问题的修复程序。

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

1. 基于 16 KB 的 Android 15 模拟器系统映像与 Android Studio Jellyfish | 2023.3.1 或更高版本兼容。不过，为了在使用 Android 15 Beta 版时获得最佳体验，请下载 最新的预览版 Android Studio。

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

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

3. 在 SDK Platforms 标签页中，选中 Show Package Details，然后展开 Android VanillaIceCream Preview 部分，并根据您要创建的虚拟设备选择以下一个或两个模拟器系统映像：

   • Google APIs Experimental 16k Page Size ARM 64 v8a System Image
   • Google APIs 实验性 16k 页面大小 Intel x86_64 Atom 系统映像
   注意： 如果您打算模拟受支持的 Google Pixel 设备，只需使用 ARM 64 v8a 系统映像即可。

   

4. 依次点击 Apply > OK 以下载您选择的任意系统映像。

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

   

警告： 如需在 x86_64 系统上模拟 16 KB 环境，您还需要完成以下步骤。这些步骤只是暂时性步骤，日后将被移除。

1. 在设备管理器中，点击 16 KB 映像旁边的三点状图标，然后点击在磁盘上显示。
2. 在此文件夹中，找到 config.ini 文件。

3. 将以下代码行添加到 config.ini 文件中，然后保存所做更改：

   kernel.parameters = androidboot.page_shift=14
   

4. 如需验证更改，请运行以下命令，该命令应返回 16384：

   adb shell getconf PAGE_SIZE
   

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

开启/关闭 Boot with 16KB page size（以 16KB 的页面大小启动）开发者页面。 选项启动设备进入 16 KB 模式。

从 Android 15 QPR1 开始，您可以执行以下操作： 请使用 Google Play 提供的特定开发者选项 设备以 16 KB 模式启动设备，并执行设备端测试。

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

• Pixel 8 和 Pixel 8 Pro（搭载 Android 15 QPR1 Beta 版 1 或更高版本）

注意： Android 15 QPR1 处于 Beta 版阶段。如需详细了解如何在符合条件的设备上获取 QPR1，请参阅获取 Android 15 QPR Beta 版 build 。