支持 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 位常量进行移位，而不是使用 1（只有 32 位）。

使用 Android App Bundle 减少大小增加

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

游戏开发者

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

• Unreal 自 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** 旁边是否有 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 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

手动刷入您的设备

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

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

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

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

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

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

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

返回公共版本

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

Android 模拟器

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

其他设备选项

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

安装和测试您的应用

测试 APK 的最简单方法是使用 Android Debug Bridge (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 位的设备上进行了彻底测试。