支持 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 段对齐情况。

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

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

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

您的应用使用任何 C/C++（原生）代码。如果您的应用使用 Android NDK，则表示您的应用使用原生代码。
您的应用链接到使用了原生库或依赖项（例如 SDK）的第三方库。
您的应用是由使用设备上原生库的第三方应用构建器构建的。

使用 APK 分析器识别原生库

APK 分析器是一个工具，可让您评估已构建 APK 的各个方面。要检查您的应用是否使用原生代码（无论是否与 16 KB 兼容），请按以下步骤操作：

打开 Android Studio，然后依次点击 File > Open，选择任一项目。
在菜单栏中，点击 Build > Analyze APK...
选择要分析的 APK。
查看 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 段的对齐情况：

将 check_elf_alignment.sh 脚本保存到文件。
在您的应用 APK 文件上运行脚本。
```
check_elf_alignment.sh APK_NAME.apk
```
脚本会为所有 arm64-v8a 共享库输出 ALIGNED 或 UNALIGNED。
如果任何 arm64-v8a 或 x86_64 共享库为 UNALIGNED，您需要更新这些库的打包方式，然后重新编译应用，并按照本部分中的步骤重新测试。

直接使用命令行工具

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

请确保已使用 Android Studio 中的 SDK 管理器或 sdkmanager 命令行工具安装了 Android SDK Build-Tools 35.0.0 或更高版本以及 Android NDK。

提取应用的 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

在您提取 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

检查输出行，确保加载段的值不小于 2**14。如果任何加载段的值为 2**13、2**12 或更低，您需要更新这些库的打包方式，然后重新编译应用，并按照本部分中的步骤重新测试。
接下来，在应用的 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 文件的名称。如果所有共享库都已正确对齐，则输出的最后一行将显示“Verification successful”。

如果验证失败，某些共享库需要重新对齐，因此您需要更新这些库的打包方式，然后重新编译应用，并按照本部分中的步骤重新测试。

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

如果您的应用使用原生代码，请按照以下各部分中概述的步骤操作，以确保您的应用支持 16 KB 设备：

更新共享库的打包方式
使用 16 KB ELF 对齐方式编译您的应用
修复代码并解决运行时问题
检查 SDK 是否支持 16 KB

更新共享库的打包方式

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

AGP 8.5.1 或更高版本

16 KB 设备要求包含未压缩共享库的应用将其对齐到 16 KB zip 对齐边界。为此，您需要升级到 Android Gradle Plugin (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-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")

Android NDK r22 及更低版本

除了 NDK r26 及更低版本中概述的步骤之外，如果您使用的是 NDK r22 或更低版本，则必须设置 common-page-size=16384。设置 common-page-size=16384 是必需的，因为早期版本的 GNU ld 和 LLVM lld 链接器存在错误。但是，我们强烈建议您将工具更新到最新版本，以完全避免这些错误。

要使用 Android NDK r22 或更低版本编译与 16 KB 兼容的共享库，您需要按如下方式更新 ndk-build 或 cmake 配置：

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

重要提示： 即使您的应用动态链接到 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，如果您的代码中有地方假定设备使用特定的页大小，您的应用也可能遇到错误。为避免这种情况，请完成以下步骤：

移除任何引用 PAGE_SIZE 常量的硬编码依赖项，或代码逻辑中假定设备页大小为 4 KB（4096）的实例。

改用 getpagesize() 或 sysconf(_SC_PAGESIZE)。
查找 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 版本与 16 KB 不兼容，您应该查看各个 SDK 提供商的网站，以确定与 16 KB 兼容的版本。

在 16 KB 环境中测试您的应用

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

设置 Android 15 SDK.
设置以下测试环境之一：
启动您的测试设备，然后运行以下命令验证其是否正在使用 16 KB 环境：
```
adb shell getconf PAGE_SIZE
```
该命令应返回一个值 16384。
运行以下 zipalign 命令以验证您的应用是否已对齐到 16 KB，其中 APK_NAME 是您应用 APK 文件的名称：
```
zipalign -c -P 16 -v 4 APK_NAME.apk
```
彻底测试您的应用，重点关注可能受更改引用特定页大小的代码实例影响的任何区域。

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

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

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

我们一直在努力开发新功能，因此请考虑在可用时下载更新版本或 Android Studio 的最新预览版本。

请记住，您可以保留已安装的现有 Android Studio 版本，因为您可以并行安装多个版本。
在 Android Studio 中，依次点击 Tools > SDK Manager。
在 SDK Platforms 标签页中，勾选 Show Package Details，然后展开 Android VanillaIceCream 或更高版本的部分，并根据您要创建的虚拟设备选择以下一个或两个模拟器系统映像：
- Google APIs 实验性 16 KB 页大小 ARM 64 v8a 系统映像
- Google APIs 实验性 16 KB 页大小 Intel x86_64 Atom 系统映像
注意： 如果您计划模拟受支持的 Google Pixel 设备，则只需要 ARM 64 v8a 系统映像。
点击 Apply > OK 下载您选择的系统映像。
按照步骤为 Android 15 设置虚拟设备，当系统提示选择系统映像时，选择您下载的 16 KB 系统映像。如果未自动推荐，您可以在 Other Images 标签页中找到 16 KB 系统映像。

某些模拟器版本和系统映像的附加步骤

对于 Android Emulator 版本 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 或更高版本中，无需执行这些步骤。

在设备管理器中，点击 16 KB 映像旁边的三个点，然后点击 Show on Disk。
在此文件夹中，找到 config.ini 文件。
在 config.ini 文件中添加以下行并保存更改：
```
kernel.parameters = androidboot.page_shift=14
```
要验证您的更改，请运行以下命令，该命令应返回 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 中的一个已知问题，在安装 Android 15 QPR2 Beta 3 并以 16 KB 模式启动设备后，Pixel 8 设备上的触摸屏无法工作。此问题不影响 Pixel 8 Pro 设备。
Pixel 8a（搭载 Android 15 QPR1 或更高版本）

警告：由于Android 15 QPR2 Beta 3 中的一个已知问题，在安装 Android 15 QPR2 Beta 3 并以 16 KB 模式启动设备后，Pixel 8a 设备上的触摸屏无法工作。
Pixel 9、9 Pro 和 9 Pro XL（搭载 Android 15 QPR2 Beta 2 或更高版本）

Google Play 兼容性要求

随着设备制造商为设备配备更多 RAM 以优化性能，许多设备将采用更大的页大小，如 16 KB。为了准备这些即将推出的设备的发布，Google Play 引入了一项兼容性要求：从 2025 年 11 月 1 日起，所有面向 Android 15+ 设备的新应用和现有应用的更新版本必须支持 16 KB 页大小。

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

支持 16 KB 页大小 使用收藏夹保持井井有条 根据您的偏好保存内容并进行分类。

优势和性能提升

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

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

使用 APK 分析器识别原生库

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

使用 check_elf_alignment.sh 脚本（Linux 或 macOS）

直接使用命令行工具

Linux 或 macOS

Windows (PowerShell)

Linux 或 macOS

Windows (PowerShell)

Linux 或 macOS

Windows (PowerShell)

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

更新共享库的打包方式

AGP 8.5.1 或更高版本

AGP 8.5 或更低版本

Groovy

Kotlin

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

Android NDK r28 及更高版本

Android NDK r27

ndk-build

Groovy

Kotlin

其他构建系统

Android NDK r26 及更低版本

ndk-build

CMake

Android NDK r22 及更低版本

ndk-build

CMake

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

检查 SDK 是否支持 16 KB

在 16 KB 环境中测试您的应用

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

某些模拟器版本和系统映像的附加步骤

启动模拟器

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

Google Play 兼容性要求

支持 16 KB 页大小