支持 64 位架构

发布在 Google Play 上的应用需要支持 64 位架构。添加应用的 64 位版本可提供性能改进，并为支持 64 位硬件的设备做好准备。

以下步骤可确保您的 32 位应用支持 64 位设备。

评估您的应用

如果您的应用仅使用用 Java 编程语言或 Kotlin 编写的代码（包括所有库或 SDK），那么您的应用支持 64 位设备。如果您的应用使用任何原生代码，或者您不确定是否使用原生代码，那么请评估您的应用。

快速状态检查

转到 Play 管理中心，查看现有版本以确定它们是否符合要求。

Play 管理中心还会显示适用于草稿版本的警告（如果有任何与 64 位要求相关的错误）。下图是一个示例。

如果出现警报，请参见以下步骤以使您的应用与 64 位设备兼容。

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

如果您的应用满足以下条件，则表示使用了原生代码

• 在您的应用中使用任何 C/C++（原生）代码。
• 链接任何第三方原生库。
• 由使用原生库的第三方应用构建器构建。

您的应用是否包含 64 位库？

检查 APK 文件的结构。构建后，APK 会与应用所需的任何原生库打包在一起。原生库存储在基于 ABI 的各种文件夹中。不需要支持每个 64 位架构，但对于支持的每个原生 32 位架构，您必须包含相应的 64 位架构。

对于 ARM 架构，32 位库位于 armeabi-v7a 中。64 位等效项为 arm64-v8a。

对于 x86 架构，请查找 32 位的 x86 和 64 位的 x86_64。

确保这两个文件夹中都包含原生库。回顾一下

请注意，根据您的应用，每个文件夹中可能存在也可能不存在完全相同的库集。目标是确保您的应用在 64 位专用环境中正常运行。

在典型情况下，为 32 位和 64 位架构构建的 APK 或应用包包含两个 ABI 的文件夹，每个文件夹都包含相应的一组原生库。如果未支持 64 位，您可能会看到一个 32 位 ABI 文件夹，但没有 64 位文件夹。

使用 APK 分析器查找原生库

APK 分析器 是一款工具，可让您评估已构建 APK 的各个方面。 使用它查找任何原生库，并确保存在 64 位库。

1. 打开Android Studio，然后打开任何项目。

2. 从菜单中选择构建 > 分析 APK…

   

3. 选择要评估的 APK。

4. 查看lib文件夹，该文件夹托管（如果有）'.so' 文件。 如果没有，则您的应用支持 64 位设备，无需执行其他操作。 如果看到armeabi-v7a或x86，则表示您拥有 32 位库。

5. 检查arm64-v8a或x86_64文件夹中是否存在类似的'.so' 文件。

   

6. 如果没有arm64-v8a或x86_64库，请更新您的构建流程，以开始在 APK 中构建和打包这些构件。

7. 如果您已经看到同时打包了两个库，则可以跳到在 64 位硬件上测试您的应用。

通过解压缩 APK 来查找原生库

APK 文件的结构类似于 zip 文件。 使用命令行或任何其他提取工具提取 APK 文件。 根据您的提取工具，您可能需要将文件重命名为 .zip。

浏览已提取的文件，按照上面的指南确定您的应用是否支持 64 位设备。 您可以从命令行运行以下命令示例

:: Command Line
> zipinfo -1 YOUR_APK_FILE.apk | grep \.so$
lib/armeabi-v7a/libmain.so
lib/armeabi-v7a/libmono.so
lib/armeabi-v7a/libunity.so
lib/arm64-v8a/libmain.so
lib/arm64-v8a/libmono.so
lib/arm64-v8a/libunity.so

在此示例中，请注意armeabi-v7a和arm64-v8a库的存在，这意味着该应用支持 64 位体系结构。

使用 64 位库构建您的应用

以下说明概述了如何构建 64 位库。 请注意，这些步骤只涵盖构建您可以从源代码构建的代码和库。

使用 Android Studio 或 Gradle 构建

大多数 Android Studio 项目使用 Gradle 作为底层构建系统，因此本节适用于这两种情况。 要为您的原生代码启用构建，请将arm64-v8a和/或x86_64（取决于您要支持的体系结构）添加到应用的 'build.gradle' 文件中的ndk.abiFilters 设置中

// Your app's build.gradle
plugins {
  id 'com.android.app'
}

android {
   compileSdkVersion 27
   defaultConfig {
       appId "com.google.example.64bit"
       minSdkVersion 15
       targetSdkVersion 28
       versionCode 1
       versionName "1.0"
       ndk.abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64'
// ...

// Your app's build.gradle
plugins {
    id("com.android.app")
}

android {
    compileSdkVersion(27)
    defaultConfig {
        appId = "com.google.example.64bit"
        minSdkVersion(15)
        targetSdkVersion(28)
        versionCode = 1
        versionName = "1.0"
        ndk {
            abiFilters += listOf("armeabi-v7a","arm64-v8a","x86","x86_64")
        }
// ...

使用 CMake 构建

如果您的应用使用CMake 构建，则可以通过将arm64-v8a传递到 '-DANDROID_ABI' 参数中来构建 64 位 ABI。

:: Command Line
> cmake -DANDROID_ABI=arm64-v8a … or
> cmake -DANDROID_ABI=x86_64 …

使用 ndk-build 构建

如果您的应用使用ndk-build构建，则可以通过使用APP_ABI变量修改'Application.mk'文件来构建 64 位 ABI

APP_ABI := armeabi-v7a arm64-v8a x86 x86_64

将 32 位代码移植到 64 位

如果您的代码已经在桌面或 iOS 上运行，则无需为 Android 做任何额外的工作。 如果这是您的代码第一次构建到 64 位系统，则您必须解决的主要问题是指针不再适合 32 位整数类型（如int）。

更新将指针存储在int、unsigned或uint32_t等类型中的代码。 在 Unix 系统上，long与指针大小匹配，但在 Windows 上并非如此。 相反，请使用揭示意图的类型uintptr_t或intptr_t。 要存储两个指针之间的差值，请使用ptrdiff_t类型。

对于非指针，也应始终优先使用<stdint.h>中定义的特定固定宽度整数类型，而不是非固定宽度类型（如int或long）。

使用以下编译器标志来捕获您的代码在指针和整数之间错误转换的情况

-Werror=pointer-to-int-cast
-Werror=int-to-pointer-cast
-Werror=shorten-64-to-32

包含int字段（用于保存指向 C/C++ 对象的指针）的 Java 类遇到了相同的问题。 在您的 JNI 源代码中搜索jint，并确保在 Java 端切换到long，在 C++ 端切换到jlong。

对于 64 位代码，隐式函数声明危险得多。 C/C++ 假设隐式声明函数（即编译器尚未看到其声明的函数）的返回类型为int。 如果您的函数的实际返回类型为指针，这在 32 位系统上运行良好，因为您的指针适合于 int。 但是，在 64 位系统上，编译器会删除指针的上半部分。 例如

// This function returns a pointer:
// extern char* foo();

// If you don't include a header that declares it,
// when the compiler sees this:
char* result = foo();

// Instead of compiling that to:
result = foo();

// It compiles to something equivalent to:
result = foo() & 0xffffffff;

// Which will then cause a SIGSEGV if you try to dereference `result`.

以下编译器标志将隐式函数声明警告转换为错误，以便您可以更轻松地查找和解决此问题

-Werror=implicit-function-declaration

如果您有内联汇编程序，请将其重写或使用普通 C/C++ 实现。

如果您有类型（例如 8 字节或 16 字节）的硬编码大小，请将它们替换为等效的sizeof(T)表达式，例如sizeof(void*)。

如果您需要为 32 位和 64 位条件编译不同的代码，可以使用#if defined(__LP64__)来进行一般性 32/64 区分，或者使用__arm__、__aarch64__（arm64）、__i386__（x86）和__x86_64__来区分 Android 支持的特定体系结构。

调整printf或scanf类似函数的格式字符串，因为传统的格式说明符不允许您以对 32 位设备和 64 位设备都正确的方式指定 64 位类型。 <inttypes.h>中的PRI和SCN宏解决了这个问题，PRIxPTR和SCNxPTR用于写入和读取十六进制指针；PRId64和SCNd64用于以可移植方式写入和读取 64 位值。

在移位时，您可能需要使用1ULL来获取要移位的 64 位常量，而不是使用1，它只有 32 位。

使用 Android App Bundle 缓解大小增加

向您的应用添加 64 位体系结构支持会导致 APK 大小增加。 我们强烈建议您利用Android App Bundle功能，将包含 32 位和 64 位原生代码的同一 APK 中的大小影响降至最低。

游戏开发者

三个最常用的引擎都支持 64 位

• 从 2015 年开始的 Unreal
• 从 2015 年开始的 Cocos2d
• 从 2018 年开始的 Unity

Unity 开发者

升级到支持的版本

Unity 通过版本2018.2和2017.4.16提供 64 位支持。

如果您使用的是不支持 64 位的 Unity 版本，请确定您要升级到的版本，并按照 Unity 提供的指南迁移您的环境，确保您的应用升级到可以构建 64 位库的版本。 Unity 建议您通过升级到最新 LTS版本的编辑器来访问最新功能和更新。

以下图表概述了各种 Unity 版本以及您应该执行的操作

更改构建设置以输出 64 位库

如果您使用的是支持 64 位 Android 库的 Unity 版本，则可以通过调整构建设置来生成应用的 64 位版本。 使用IL2CPP 后端作为您的脚本后端。 要设置您的 Unity 项目以构建 64 位体系结构，请执行以下操作

1. 转到构建设置，并通过验证平台下的Android旁边是否有 Unity 符号来确保您正在构建 Android。 1. 如果 Unity 符号不在 Android 平台旁边，请选择Android，然后点击切换平台。

2. 点击播放器设置。

   

3. 导航到播放器设置面板 > Android 设置 > 其他设置 > 配置

4. 将脚本后端设置为IL2CPP。

5. 选中目标体系结构 > ARM64复选框。

   

6. 照常构建！

请注意，构建 ARM64 需要将所有资产专门构建到该平台。 请遵循 Unity 的指南来减小 APK 大小，并考虑利用Android App Bundle功能来帮助缓解这种大小增加。

多 APK 和 64 位合规性

如果您使用 Google Play 的多 APK 支持发布您的应用，请注意，对 64 位要求的合规性是在发布级别评估的。 但是，64 位要求不适用于未分发到运行 Android 9 Pie 或更高版本的设备的 APK 或应用包。

如果您的一个 APK 被标记为不符合要求，但它是早期版本，无法使其符合要求，则一种策略是在该 APK 清单的uses-sdk元素中添加maxSdkVersion="27"属性。 此 APK 不会分发到运行 Android 9 Pie 或更高版本的设备，并且不再阻止合规性。

RenderScript 和 64 位合规性

如果您的应用使用 RenderScript，并且使用的是早期版本的 Android 工具构建的，则您可能会在应用中看到 64 位合规性问题。 使用低于 21.0.0 的构建工具时，编译器可能会将位代码生成到外部.bc文件中。 这些旧版.bc文件不再支持 64 位体系结构，因此 APK 中存在该文件会导致合规性问题。

要解决此问题，请删除项目中的所有.bc文件，将您的环境升级到build-tools-21.0.0或更高版本，并在 Android Studio 中将renderscriptTargetApi设置为 21+，以指示编译器不要发出.bc文件。 然后，重建您的应用，检查.bc文件，并上传到 Play 管理中心。

在 64 位硬件上测试您的应用

您的应用程序的 64 位版本应提供与 32 位版本相同的质量和功能集。测试您的应用程序以确保最新 64 位设备上的用户在您的应用程序中拥有良好的体验。

仅支持 64 位的设备

我们建议您尽可能使用以下选项之一，在严格的仅支持 64 位的环境中测试您的应用程序。

• 带有仅支持 64 位系统映像的 Google Pixel
• Android 模拟器

带有仅支持 64 位系统映像的 Google Pixel

为了方便应用程序开发和测试，我们为一些 Pixel 设备提供了具有严格仅支持 64 位环境的特殊系统映像。这些仅支持 64 位的映像最初与 Android 13 和 14 预览版发布的标准出厂系统映像同时提供，但您可以在测试应用程序的 64 位兼容性时继续使用它们。

获取仅支持 64 位的映像

与出厂系统映像类似，您可以将仅支持 64 位的映像刷入您的设备 使用 Android 刷机工具 或通过 手动刷机，如下面的部分所述。

使用 Android 刷机工具刷机

Android 刷机工具 可让您将系统映像安全地刷入支持的 Pixel 设备。Android 刷机工具适用于任何支持 WebUSB 的 Web 浏览器，例如 Chrome 或 Edge 79+。

Android 刷机工具会逐步引导您完成刷机设备的过程，无需安装任何工具，但您需要解锁设备并 在开发者选项中启用 USB 调试。有关完整说明，请参阅 Android 刷机工具文档。

通过 USB 连接您的设备，然后根据您要刷入的系统映像类型，使用以下链接之一导航到 Android 刷机工具并按照屏幕上的指导进行操作。

• Android 14（Beta 5.2）仅支持 64 位的系统映像

  选择您要刷机的设备

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

• Android 13（QPR3 Beta 3.2）仅支持 64 位的系统映像

  选择您要刷机的设备

  • Pixel 4a (5G)
  • Pixel 5
  • Pixel 6
  • Pixel 6 Pro

手动刷机

您还可以下载最新的系统映像并将其手动刷入您的设备。请参阅下表以下载测试设备的系统映像。手动刷机设备在您需要对测试环境进行精确控制或需要频繁重新安装时很有用，例如在执行自动化测试时。

备份设备数据并下载匹配的系统映像后，您可以 将映像刷入您的设备。

您可以随时选择 恢复到最新的公开版本。

适用于 Android 14（Beta 5.3）的仅支持 64 位的出厂映像

这些映像提供了一个严格的仅支持 64 位的环境，用于测试 64 位应用程序兼容性。这些仅支持 64 位的配置仅供开发人员使用。

适用于 Android 13（QPR3 Beta 3.2）的仅支持 64 位的出厂映像

这些映像提供了一个严格的仅支持 64 位的环境，用于测试 64 位应用程序兼容性。这些仅支持 64 位的配置仅供开发人员使用。

恢复到公开版本

您可以使用 Android 刷机工具 刷入出厂映像，或者从 Nexus 和 Pixel 设备的出厂映像 页面获取出厂规范系统映像，然后将其手动刷入设备。

Android 模拟器

从 Android 12（API 级别 31）开始，Android 模拟器系统映像仅支持 64 位。使用具有 Android 12（API 级别 31）或更高版本的系统映像 创建 Android 虚拟设备 (AVD)，以便为应用程序测试获得严格的仅支持 64 位的环境。

其他设备选项

如果您没有这些设备之一，或无法使用 Android 模拟器，您的下一个最佳选择是使用支持 64 位的设备，例如 Google Pixel 或其他设备制造商的最新旗舰设备。

安装并测试您的应用程序

测试 APK 的最简单方法是使用 Android 调试桥 (adb) 安装应用程序。在大多数情况下，您可以提供 --abi 作为参数，以指示要安装到设备的库。这将仅在设备上安装应用程序的 64 位库。

:: Command Line
# A successful install:
> adb install --abi armeabi-v7a YOUR_APK_FILE.apk
Success

# If your APK does not have the 64-bit libraries:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
adb: failed to install YOUR_APK_FILE.apk: Failure [INSTALL_FAILED_NO_MATCHING_ABIS: Failed to extract native libraries, res=-113]

# If your device does not support 64-bit, an emulator, for example:
> adb install --abi arm64-v8a YOUR_APK_FILE.apk
ABI arm64-v8a not supported on this device

成功安装后，像往常一样测试您的应用程序，以确保其质量与 32 位版本相同。

检查已知的兼容性问题

在测试时，检查您的应用程序是否有以下问题，这些问题会影响应用程序在 64 位设备上运行时的行为。即使您的应用程序不直接依赖于受影响的库，应用程序依赖项中的第三方库和 SDK 也可能依赖于这些库。

SoLoader

如果您使用的是本机代码加载器 SDK SoLoader，请更新到 v0.10.4 或更高版本。如果您的应用程序使用依赖于 SoLoader 的 SDK，请确保也更新到受影响 SDK 的最新稳定版本。

SoLoader v0.9.0 及更低版本假设系统库存在于 /vendor/lib:/system/lib 中。此错误在 Pixel 7 等存在该路径的设备中不可见，但在仅在 /vendor/lib64:/system/lib64 中具有系统库的设备中会导致崩溃。

有关修复此问题以及 SoLoader 导致的其他问题的更多信息，请参阅 Google 帮助中心中的相应答案。

OpenSSL

如果您使用的是 OpenSSL 库，请更新到 OpenSSL 1.1.1i 或更高版本。如果您的应用程序使用提供使用 HTTPS 的通信的 SDK，或其他依赖于 OpenSSL 的 SDK，请确保也更新到使用更新版本的 OpenSSL 的 SDK 的最新版本。如果不可用，请联系 SDK 提供商。

ARMv8.3 PAC 通过在运行时验证指针来启用硬件辅助的控制流完整性。早期版本的 OpenSSL 错误地使用了这些功能，导致所有基于 ARMv8.3a 及更高版本的处理器的设备在运行时崩溃。

有关修复此问题以及 OpenSSL 导致的其他问题的更多信息，请参阅 Google 帮助中心中的相应答案。

BTI

ARMv8.5 及更高版本使用分支目标指令 (BTI) 来帮助防止 JOP 攻击。早期版本的混淆 SDK 会分支到使用 BTI 构建的库的随机偏移量，这会导致应用程序崩溃。由于这些指令被编码为 HINT，因此此错误在不支持 BTI 的设备中不可见。

发布

当您认为您的应用程序已准备就绪时，可以照常发布。与往常一样，继续遵循部署应用程序的最佳实践。我们建议您利用 封闭测试轨道 将应用程序推广到有限数量的用户，以确保您的应用程序的质量始终如一。

与推出主要更新时一样，请确保在向更广泛的受众发布之前，您已在支持 64 位的设备上进行了彻底测试。