支持 64 位架构

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

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

评估您的应用

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

快速状态检查

前往 Play 管理中心并查看现有版本，了解它们是否合规。

如果您的草稿版本存在与 64 位要求相关的任何问题，Play 管理中心也会显示警告。以下图片是一个示例。

如果出现提醒，请参阅以下步骤，使您的应用与 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 或 App Bundle 包含两个 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 构建的，您可以通过修改您的 'Application.mk' 文件并使用 APP_ABI 变量来构建 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。如果函数的实际返回类型是指针，那么在指针适合 int 的 32 位系统上这工作正常。然而，在 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 位支持。

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

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

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

如果您使用的 Unity 版本支持 64 位 Android 库，您可以通过调整构建设置生成应用的 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 管理中心。

在 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 的任何网络浏览器，例如 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 位的设备上进行了彻底测试。