支持 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 或 bundle 都包含这两种 ABI 的文件夹，每个文件夹都包含一组相应的原生库。如果不支持 64 位，您可能会看到 32 位 ABI 文件夹，但没有 64 位文件夹。

使用 APK Analyzer 查找原生库

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

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

2. 从菜单中选择 Build > Analyze 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 位：

• 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. 转到 Build Settings，通过验证 Platform 下的 Android 旁边是否有 Unity 符号，确保您正在为 Android 构建。1. 如果 Unity 符号不在 Android 平台旁边，请选择 Android 并点击 Switch Platform。

2. 点击 Player settings。

   

3. 导航到 Player Settings Panel > Settings for Android > Other settings > Configuration

4. 将 Scripting Backend 设置为 IL2CPP。

5. 选中 Target Architecture > ARM64 复选框。

   

6. 正常构建！

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

多 APK 和 64 位合规性

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

如果您的某个 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 或其他依赖于 OpenSSL 的 SDK 提供通信的 SDK，请务必也更新到使用较新 OpenSSL 版本的 SDK 的最新版本。如果不可用，请联系 SDK 提供商。

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

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

BTI

ARMv8.5 及更高版本使用分支目标指令 (BTI) 来帮助防止JOP 攻击。早期版本的混淆 SDK 在带有 BTI 的库的随机偏移处进行分支，可能导致应用崩溃。由于指令编码为HINT，因此此错误在不支持 BTI 的设备中不可见。

发布

当您认为您的应用已准备就绪时，像往常一样发布。一如既往，请继续遵循部署应用的最佳实践。我们建议利用封闭式测试轨道向有限数量的用户推出，以确保您的应用质量保持一致。

与推出重大更新一样，在向更广泛的受众发布之前，请务必在支持 64 位的设备上彻底测试。