Suporte a tamanhos de página de 16 KB

Requisito de compatibilidade de 16 KB do Google Play

A partir de 1º de novembro de 2025, todos os novos apps e atualizações de apps enviados ao Google Play e destinados a dispositivos com o Android 15 ou mais recente precisarão oferecer suporte a tamanhos de página de 16 KB em dispositivos de 64 bits.

Saiba mais →

从历史上看，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 环境中测试应用。

Benefícios e ganhos de performance

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

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

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

Verificar se o app foi afetado

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

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

O app usa código nativo?

Seu app usa código nativo se alguma das seguintes condições for verdadeira:

• O app usa código C/C++ (nativo). Se o app usa o Android NDK, ele usa código nativo.
• O app se vincula a bibliotecas ou dependências nativas de terceiros (como SDKs) que as usam.
• O app é criado por um criador de apps de terceiros que usa bibliotecas nativas no dispositivo.

Identificar bibliotecas nativas usando o APK Analyzer

O APK Analyzer é uma ferramenta que permite avaliar vários aspectos de um APK. Para verificar se o app usa código nativo (independentemente de ser compatível com 16 KB):

1. Abra o Android Studio, clique em File > Open e escolha qualquer projeto.

2. Na barra de menus, clique em Build > Analyze APK…

   

3. Escolha o APK que você quer analisar.

4. Confira se há algum arquivo de objeto compartilhado (.so) na pasta lib. Se houver arquivos de objeto compartilhado, o app usa código nativo. A coluna Alignment mostra mensagens de aviso para arquivos que têm problemas de alinhamento. Se não houver arquivos de objeto compartilhado ou se não houver uma pasta lib, o app não usa código nativo.

   

Detectar problemas de alinhamento com verificações automatizadas

O Android Studio avisa proativamente se as bibliotecas ou APKs pré-criados não forem compatíveis com 16 KB. Use a ferramenta APK Analyzer para revisar quais bibliotecas precisam ser atualizadas ou se alguma mudança de código é necessária.

O Lint no Android Studio também destaca bibliotecas nativas que não estão alinhadas com 16 KB.

Verificar o alinhamento de segmentos ELF para bibliotecas compartilhadas

Para qualquer biblioteca compartilhada, verifique se os segmentos ELF estão alinhados corretamente usando o alinhamento ELF de 16 KB. Se você estiver desenvolvendo no Linux ou no macOS, poderá usar o script check_elf_alignment.sh, conforme descrito na seção a seguir. Também é possível usar as ferramentas de linha de comando diretamente.

Usar o script check_elf_alignment.sh (Linux ou macOS)

Siga estas etapas para verificar o alinhamento de segmentos ELF usando o script check_elf_alignment.sh:

1. Salve o check_elf_alignment.sh script em um arquivo.

2. Execute o script no arquivo APK do app:

   check_elf_alignment.sh APK_NAME.apk
   

   O script gera ALIGNED ou UNALIGNED para todas as arm64-v8a bibliotecas compartilhadas.

3. Se alguma biblioteca compartilhada arm64-v8a ou x86_64 estiver UNALIGNED, será necessário atualizar o pacote dessas bibliotecas, recompilar o app e testar novamente seguindo as etapas desta seção.

Usar ferramentas de linha de comando diretamente

Siga estas etapas para verificar o alinhamento de segmentos ELF usando ferramentas de linha de comando diretamente:

1. Verifique se o SDK do Android Build-Tools versão 35.0.0 ou mais recente e o Android NDK estão instalados usando o SDK Manager no Android Studio ou sdkmanager ferramenta de linha de comando.

2. Extraia o arquivo APK do app:

   Linux ou macOS

   unzip APK_NAME.apk -d /tmp/my_apk_out
   

   Windows (PowerShell)

   Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
   

3. No diretório temporário em que você extraiu o arquivo APK, verifique o conteúdo do diretório lib para arquivos de objeto compartilhado (.so). Esses são os mesmos arquivos de objeto compartilhado que você teria visto ao identificar bibliotecas nativas usando o APK Analyzer. Execute o comando a seguir em cada arquivo de objeto compartilhado:

   Linux ou 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"
   

   Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android, SHARED_OBJECT_FILE é o nome do arquivo de objeto compartilhado que você está verificando e NDK_VERSION é a versão do Android NDK que você instalou (por exemplo, 28.0.12433566). A saída será semelhante à seguinte para cada arquivo que você verificar:

   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. Verifique as linhas de saída para garantir que os segmentos de carregamento não tenham valores menores que 2**14. Se algum segmento de carregamento for 2**13, 2**12 ou valores mais baixos , será necessário atualizar o pacote dessas bibliotecas, então recompilar seu app e testar novamente seguindo as etapas desta seção.

5. Em seguida, execute a ferramenta de linha de comando zipalign no arquivo APK do app:

   Linux ou 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
   

   Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android e APK_NAME é o nome do arquivo APK do app. A última linha da saída vai dizer "Verification successful" se todas as bibliotecas compartilhadas estiverem alinhadas corretamente.

   Se a verificação falhar, algumas bibliotecas compartilhadas precisarão ser realinhadas. Portanto, será necessário atualizar o pacote dessas bibliotecas, então recompilar o app e testar novamente seguindo as etapas desta seção.

Criar o app com suporte a dispositivos de 16 KB

Se o app usa código nativo, conclua as etapas descritas nas seções a seguir para garantir que ele ofereça suporte a dispositivos de 16 KB:

1. Atualizar o pacote das bibliotecas compartilhadas
2. Compilar o app usando o alinhamento ELF de 16 KB
3. Corrigir o código e resolver problemas de execução
4. Verificar se os SDKs oferecem suporte a 16 KB

Dica: se você atualizar suas ferramentas para as versões mais recentes (AGP versão 8.5.1 ou mais recente e NDK versão r28 ou mais recente) e usar dependências pré-criadas compatíveis com 16 KB, o app será compatível com 16 KB por padrão. Você pode pular para a etapa de correção do código e resolução de problemas de execução.

Atualizar o pacote das bibliotecas compartilhadas

Faça upgrade para a versão 8.5.1 ou mais recente do AGP e use bibliotecas compartilhadas não compactadas.

Usar bundletool para verificar o alinhamento do ZIP

Para conferir o alinhamento do pacote, use:

bundletool dump config --bundle=<my .aab>  | grep alignment

Se você vir PAGE_ALIGNMENT_16K, isso significa que o pacote solicita o alinhamento do ZIP de 16 KB. Se você vir PAGE_ALIGNMENT_4K, isso instrui o APK criado a partir desse AAB a ter arquivos .so alinhados de 4 KB no arquivo ZIP.

AGP versão 8.5.1 ou mais recente

Dispositivos de 16 KB exigem que os apps enviados com bibliotecas compartilhadas não compactadas as alinhem em um limite de 16 KB alinhado ao ZIP. Para fazer isso, é necessário fazer upgrade para a versão 8.5.1 ou mais recente do Plug-in do Android para Gradle (AGP). Consulte a seção Assistente de upgrade do Plug-in do Android para Gradle para detalhes sobre o processo de upgrade.

AGP versão 8.5 ou anterior

Observação: nas versões 8.3 a 8.5 do AGP, os apps são alinhados a 16 KB por padrão. No entanto, o bundletool não zipalinha APKs por padrão. Portanto, o app pode parecer funcionar, mas, quando criado a partir de um pacote no Google Play, ele não será instalado.

Se não for possível fazer upgrade do AGP para a versão 8.5.1 ou mais recente, a alternativa é mudar para o uso de bibliotecas compartilhadas compactadas. Atualize a configuração do Gradle para que ele compacte as bibliotecas compartilhadas ao empacotar o app para evitar problemas de instalação com bibliotecas compartilhadas não alinhadas.

Groovy

No arquivo build.gradle, adicione a seguinte opção:

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

Kotlin

No arquivo build.gradle.kts, adicione a seguinte opção:

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

AGP versão 8.0 ou anterior

Se você estiver usando uma versão do AGP igual ou anterior à 8.0, também será necessário desativar a opção de biblioteca nativa não compactada para pacotes de apps no arquivo gradle.properties:

android.bundle.enableUncompressedNativeLibs=false

Aviso: quando você usa bibliotecas compartilhadas compactadas, o app ocupa mais espaço quando instalado, porque as bibliotecas são extraídas do APK e copiadas para o disco. O app pode falhar com mais frequência na instalação porque esse aumento no uso do disco significa que há menos espaço no dispositivo. Para evitar isso, faça upgrade para a versão 8.5.1 ou mais recente do AGP.

Compilar o app usando o alinhamento ELF de 16 KB

Dispositivos de 16 KB exigem que os segmentos ELF das bibliotecas compartilhadas sejam alinhados corretamente usando o alinhamento ELF de 16 KB para que o app seja executado.

Para desenvolvedores de jogos, se o jogo for executado no mecanismo de jogos do Unity, consulte o guia do Unity. Se o jogo for executado no mecanismo de jogos do Unreal, consulte o guia do Unreal. Para mecanismos de jogos nativos, continue com este guia.

Observação: se o app não extrair bibliotecas nativas para o sistema de arquivos (extractNativeLibs definido como false), você provavelmente vai notar um pequeno aumento no tamanho binário do app após a compilação usando um alinhamento ELF de 16 KB. As otimizações do gerenciador de pacotes no Android 15 negam os custos de execução desse aumento.

Para compilar o app usando o alinhamento ELF de 16 KB, conclua as etapas em uma das seções a seguir, dependendo da versão do Android NDK que você está usando.

Importante: se o app usa bibliotecas compartilhadas pré-criadas, também é necessário recompilá-las da mesma forma e reimportar as bibliotecas alinhadas de 16 KB para o app.

Android NDK r28 e versões mais recentes

O NDK versão r28 e mais recentes são compilados com alinhamento de 16 KB por padrão.

Android NDK r27 e versões anteriores

Para oferecer suporte à compilação de bibliotecas compartilhadas alinhadas de 16 KB com o Android NDK versão r27 ou anterior, use as seguintes flags do vinculador:

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

Veja como atualizar os arquivos de configuração do sistema de build:

ndk-build

Se você estiver usando o ndk-build, atualize o Android.mk para ativar o alinhamento ELF de 16 KB:

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

CMake

Se você estiver usando o CMake, atualize o CMakeLists.txt para ativar o alinhamento ELF de 16 KB:

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

Observação: mesmo que o app se vincule dinamicamente à biblioteca padrão C++ (libc++_shared.so) do NDKs r26 e versões anteriores, algumas das quais não têm um libc++_shared.so alinhado de 16 KB, ainda é necessário atualizar o alinhamento de todas as outras bibliotecas aqui e atualizar o código para evitar depender de PAGE_SIZE. Para testar essas versões mais antigas do NDK em dispositivos de 16 KB, as versões Canary das versões LTS do NDK r23 e r25 estão disponíveis no Android CI com bibliotecas libc++_shared.so alinhadas de 16 KB.

Observação: se não for possível migrar para o Android NDK mais recente, talvez seja possível atualizar o app para compilar estaticamente a biblioteca padrão C++ na biblioteca compartilhada. Consulte a seção Suporte à biblioteca C++ para detalhes sobre a vinculação estática à biblioteca padrão C++ e leia a seção Considerações importantes.

Corrigir o código e resolver problemas de execução

Mesmo que o app esteja alinhado a 16 KB, ele poderá encontrar erros se os locais no código presumirem que um dispositivo está usando um tamanho de página específico. Para evitar isso, siga estas etapas:

1. Remova todas as dependências codificadas que referenciam a PAGE_SIZE constante ou instâncias na lógica de código que presumem que o tamanho da página de um dispositivo é de 4 KB (4096).

   Use getpagesize() ou sysconf(_SC_PAGESIZE).

2. Procure usos de mmap() e outras APIs que exigem argumentos alinhados à página e substitua por alternativas quando necessário.

Em alguns casos, se o app usar PAGE_SIZE como um valor conveniente que não está vinculado ao tamanho da página subjacente, isso não fará com que o app seja interrompido quando usado no modo de 16 KB. No entanto, se esse valor for transmitido ao kernel com mmap sem MAP_FIXED, o kernel ainda usará uma página inteira, o que desperdiça memória. Por esses motivos, PAGE_SIZE não é definido quando o modo de 16 KB está ativado no NDK r27 e versões mais recentes.

Se o app usa PAGE_SIZE dessa forma e nunca transmite esse valor diretamente ao kernel, em vez de usar PAGE_SIZE, crie uma nova variável com um novo nome para refletir que ela é usada para outras finalidades e não reflete uma página de memória real.

Verificar se os SDKs oferecem suporte a 16 KB

Muitos SDKs são compatíveis com tamanhos de página de 16 KB, principalmente se você os criar ou receber versões pré-criadas recentes. No entanto, como algumas versões pré-criadas ou versões do SDK não são compatíveis com 16 KB, verifique o site de cada provedor de SDK para determinar qual versão usar com 16 KB.

Testar o app em um ambiente de 16 KB

Depois de criar o app com suporte a dispositivos de 16 KB, teste-o em um ambiente de 16 KB para verificar se ele apresenta regressões. Para isso, siga estas etapas:

1. Configure o SDK do Android 15 ou mais recente.

2. Configure um dos seguintes ambientes de teste:

   • Configure o Android Emulator com uma imagem do sistema Android 15 baseada em 16 KB
     • Use o Cuttlefish com tamanho de página de 16 KB no ARM64
     • Simule o Cuttlefish com tamanho de página de 16 KB no x86-64
   • Ative o modo de 16 KB em um dispositivo usando as opções do desenvolvedor
   • Use o Samsung Remote Test Lab em dispositivos com suporte a 16 KB

3. Inicie o dispositivo de teste e execute o comando a seguir para verificar se ele está usando um ambiente de 16 KB:

   adb shell getconf PAGE_SIZE
   

   O comando precisa retornar um valor de 16384.

4. Execute o comando zipalign a seguir para verificar se o app está alinhado a 16 KB, em que APK_NAME é o nome do arquivo APK do app:

   zipalign -c -P 16 -v 4 APK_NAME.apk
   

5. Teste o app completamente, concentrando-se em áreas que podem ser afetadas por mudança de instâncias de código que referenciam tamanhos de página específicos.

Configurar o Android Emulator com uma imagem do sistema baseada em 16 KB

Para configurar um ambiente de 16 KB usando o Android Emulator, siga estas etapas:

1. No Android Studio, clique em Tools > SDK Manager.

2. Na guia SDK Platforms, marque a caixa Show Package Details, expanda a seção Android VanillaIceCream ou mais recente e selecione uma ou ambas as imagens do sistema do emulador a seguir, dependendo dos dispositivos virtuais que você quer criar:

   • Google APIs Experimental 16 KB Page Size ARM 64 v8a System Image
   • Google APIs Experimental 16 KB Page Size Intel x86_64 Atom System Image
   Observação: se você planeja emular um dispositivo Google Pixel compatível, só vai precisar da imagem do sistema ARM 64 v8a.

   

3. Clique em Apply > OK para fazer o download das imagens do sistema selecionadas.

4. Siga as etapas para configurar um dispositivo virtual para o Android 15 e, quando solicitado a selecionar uma imagem do sistema, selecione a imagem do sistema de 16 KB que você fez o download. Se ela não for recomendada automaticamente, você poderá encontrar a imagem do sistema de 16 KB na guia Other Images.

   

Iniciar o emulador

Depois de terminar de configurar o Android Emulator e os dispositivos virtuais, inicie o emulador no menu do dispositivo de destino ou na linha de comando.

Ativar o modo 16 KB em um dispositivo usando as opções do desenvolvedor

Ative a opção de desenvolvedor Inicializar com tamanho de página de 16 KB para inicializar um dispositivo no modo de 16 KB.

Nas versões QPR do Android 15, é possível usar a opção do desenvolvedor disponível em alguns dispositivos para inicializar o dispositivo no modo de 16 KB e realizar testes no dispositivo. Antes de usar a opção do desenvolvedor, acesse Configurações > Sistema > Atualizações de software e aplique as atualizações disponíveis.

Essa opção para desenvolvedores está disponível nos seguintes dispositivos:

• Pixel 8 e 8 Pro (com Android 15 QPR1 ou versões mais recentes)

• Pixel 8a (com Android 15 QPR1 ou versões mais recentes)

• Pixel 9, 9 Pro e 9 Pro XL (com Android 15 QPR2 ou versões mais recentes)

• Pixel 9a (com Android 16 ou versões mais recentes)

Modo de compatibilidade com versões anteriores de 16 KB

Aviso no modo de compatibilidade de tamanho de página

A opção de compatibilidade com versões anteriores de 16 KB está disponível quando um dispositivo está em execução com um kernel de 16 KB. O gerenciador de pacotes executa um app no modo de compatibilidade com versões anteriores de 16 KB quando as seguintes condições são atendidas:

• Se o app tiver arquivos ELF (com uma extensão .so) com um alinhamento de segmento LOAD de 4 KB.
• Se o APK compactado tiver arquivos ELF não compactados que estejam alinhados ao ZIP de 4 KB.

Se o gerenciador de pacotes tiver ativado o modo de compatibilidade com versões anteriores de 16 KB para um app, ele vai mostrar um aviso quando for iniciado pela primeira vez, informando que está em execução no modo de compatibilidade com versões anteriores de 16 KB.

O modo de compatibilidade com versões anteriores de 16 KB permite que alguns apps funcionem, mas, para melhor confiabilidade e estabilidade, os apps ainda precisam estar alinhados a 16 KB.

Na página de informações do app, em Advanced, ative ou desative a configuração Run app with page size compat mode para ativar ou desativar o modo de compatibilidade com versões anteriores de 16 KB para um app específico. Essa configuração só fica visível quando o dispositivo está em execução com tamanho de página de 16 KB.

Configuração do modo de compatibilidade de tamanho de página

Para forçar a compatibilidade com versões anteriores de 16 KB para todos os apps no dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled true
adb shell setprop pm.16kb.app_compat.disabled false

Para forçar a desativação da compatibilidade com versões anteriores de 16 KB para todos os apps no dispositivo:

adb shell setprop bionic.linker.16kb.app_compat.enabled false
adb shell setprop pm.16kb.app_compat.disabled true

No Android 17, também é possível forçar a desativação da compatibilidade com versões anteriores de 16 KB para todos os apps e fazer com que qualquer binário incompatível seja interrompido imediatamente:

    adb shell setprop bionic.linker.16kb.app_compat.enabled fatal
    adb shell setprop pm.16kb.app_compat.disabled true

Defina a propriedade android:pageSizeCompat como ativada ou desativada para ativar ou desativar o modo de compatibilidade com versões anteriores para um app específico no AndroidManifest.xml. Quando essa propriedade é definida, o app não mostra avisos de modo de compatibilidade com versões anteriores quando é iniciado.

Requisito de compatibilidade do Google Play

À medida que os fabricantes de dispositivos equipam os dispositivos com mais RAM para otimizar a performance, muitos vão adotar tamanhos de página maiores, como 16 KB. Para se preparar para o lançamento desses dispositivos futuros, o Google Play está introduzindo um novo requisito de compatibilidade: a partir de 1º de novembro de 2025, todos os novos apps e atualizações de apps enviados ao Google Play e destinados a dispositivos com o Android 15 (nível 35 da API) e mais recentes precisarão oferecer suporte a tamanhos de página de 16 KB.

Para saber mais sobre esse requisito de compatibilidade, consulte esta postagem do blog.