支持 64 位架构

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

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

评估您的应用

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

快速状态检查

转到 Play Console 并查看现有版本以查看它们是否符合要求。

如果存在与 64 位要求相关的任何问题，Play Console 还会显示适用于您的草稿版本的警告。下图是一个示例。

如果出现警报，请参阅以下步骤以使您的应用与 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

包含指向 C/C++ 对象的指针的 int 字段的 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 位常量进行移位，而不是使用仅为 32 位的 1。

使用 Android App Bundle 降低大小增长

为您的应用添加 64 位架构支持可能会导致 APK 大小增加。我们强烈建议您利用 Android App Bundle 功能，最大程度地减少在同一 APK 中包含 32 位和 64 位原生代码带来的大小影响。

游戏开发者

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

• 虚幻引擎自 2015 年起
• Cocos2d 自 2015 年起
• Unity 自 2018 年起

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 构建，方法是验证 **平台** 下的 **Android** 旁边是否有 Unity 符号。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 Console。

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

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

仅 64 位设备

在可能的情况下，我们建议您使用以下选项之一在严格的仅 64 位环境中测试您的应用

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

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

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

获取仅 64 位映像

与工厂系统映像类似，您可以 使用 Android Flash Tool 或 手动刷机 将仅 64 位映像刷入您的设备，如下文所述。

使用 Android Flash Tool 刷机

Android Flash Tool 允许您安全地将系统映像刷入受支持的 Pixel 设备。Android Flash Tool 可与任何支持 WebUSB 的 Web 浏览器（如 Chrome 或 Edge 79+）配合使用。

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

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

• 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

手动刷机

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

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

您可以随时选择 返回到最新的公共版本。

仅限 64 位的 Android 14 工厂镜像 (Beta 5.3)

这些镜像提供了一个严格的仅限 64 位的环境，用于测试 64 位应用的兼容性。这些仅限 64 位的配置仅供开发者使用。

仅限 64 位的 Android 13 工厂镜像 (QPR3 Beta 3.2)

这些镜像提供了一个严格的仅限 64 位的环境，用于测试 64 位应用的兼容性。这些仅限 64 位的配置仅供开发者使用。

返回公共版本

您可以使用 Android Flash 工具刷入工厂镜像，或者从Nexus 和 Pixel 设备的工厂镜像页面获取工厂规格系统镜像，然后手动刷入设备。

Android 模拟器

从 Android 12（API 级别 31）开始，Android 模拟器系统镜像仅限 64 位。创建 Android 虚拟设备 (AVD)，使用 Android 12（API 级别 31）或更高版本的系统镜像，以获得严格的仅限 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 位的设备上进行了彻底的测试。