Android Studio 和 Android Gradle 插件的已知问题

本页记录了 Android Studio 4.1 和 Android Gradle 插件 4.1 的已知问题。如果您遇到本页尚未提及的问题，请报告错误。

升级到预览版：我们发布每个版本的 Android Studio 和 Android Gradle 插件都是为了提高稳定性和性能以及增加一些新功能。如需立即体验即将推出的版本的优势，请下载并安装 Android Studio 预览版。

Android Studio 的已知问题

本部分将介绍最新稳定版 Android Studio 中存在的已知问题。

Android Studio 在 macOS Big Sur 上卡死

在运行 macOS Big Sur 的计算机上，Android Studio 4.1 可能会在您打开对话框时卡死。

如需解决此问题，请执行以下任一操作：

转到 Apple 菜单，依次选择系统偏好设置 > 通用。在首选以标签页方式打开文稿选项中，选择“永不”。然后重启 Android Studio。
升级到 Android Studio 4.2（目前提供 Beta 版）。

使用 Database Inspector 的应用在 Android 11 模拟器上发生崩溃问题

使用 Database Inspector 的应用在 Android 11 模拟器上运行时可能会崩溃；如发生崩溃，logcat 中会显示如下错误：

 Fatal signal 11 (SIGSEGV), code 1 (SEGV_MAPERR)

要想解决此问题，请将 Android 11 模拟器升级到版本 9 或更高版本，方法如下：依次转到 Tools > SDK Manager，在 SDK Platforms 标签页中，选中标签为 Show Package Details 的复选框，然后选择 Android 11 模拟器修订版 9 或更高版本。

Studio 在升级后没有启动

如果 Studio 在升级后没有启动，可能是因为从旧版 Android Studio 导入的 Android Studio 配置无效或插件不兼容。为了解决此问题，请根据所使用的 Android Studio 版本和操作系统，尝试删除以下目录（或重命名以下目录，以作备份），然后再次启动 Android Studio。这会将 Android Studio 重置为其默认状态，并移除所有第三方插件。

对于 Android Studio 4.1 及更高版本：

Windows：%APPDATA%\Google\AndroidStudio<version>
示例：C:\Users\your_user_name\AppData\Roaming\Google\AndroidStudio4.1
macOS：~/Library/Application Support/Google/AndroidStudio<version>
示例：~/Library/Application Support/Google/AndroidStudio4.1
Linux：~/.config/Google/AndroidStudio<version> 和 ~/.local/share/Google/AndroidStudio<version>
示例：~/.config/Google/AndroidStudio4.1 和 ~/.local/share/Google/AndroidStudio4.1

对于 Android Studio 4.0 及更低版本：

Windows：%HOMEPATH%\.AndroidStudio<version>\config
示例：C:\Users\your_user_name\.AndroidStudio3.6\config
macOS：~/Library/Preferences/AndroidStudio<version>
示例：~/Library/Preferences/AndroidStudio3.6
Linux：~/.AndroidStudio<version>/config
示例：~/.AndroidStudio3.6/config

请注意，Android Studio Canary 版和 Beta 版的配置目录是 PreviewX.Y（而不是用于 <version> 的 X.Y）。例如，Android Studio 4.1 Canary build 使用的是 AndroidStudioPreview4.1 目录，而不是 AndroidStudio4.1 目录，后者用于候选版本和稳定版本。

Kotlin 多平台项目中的编译问题

Kotlin MPP 代码中可能会因缺少符号而出现编译错误。将 Kotlin 插件升级到版本 1.4 应该能解决此问题。

如果您对操作按钮的 Run/Debug 组进行了自定义（例如，通过在 Settings 或 Preferences 窗口中的 Appearance & Behavior > Menus and Toolbars 下修改选项），那么在您重启 IDE 后，这些操作按钮可能会从工具栏中消失。这是 Android Studio 4.0 所基于的 IntelliJ 版本的已知问题（请参阅问题 IDEA-228450）。

若要解决此问题，请按照以下方法还原您对这些按钮所做的任何自定义：

依次选择 File > Settings（或在 macOS 上，依次选择 Android Studio > Preferences）。
在窗口左侧，依次转到 Appearance & Behavior > Menus and Toolbars。
在窗口右侧，依次转到 Main Toolbar > Toolbar Run Actions，然后选择 Run/Debug。
点击窗口顶部附近的 Revert 图标，然后选择 Restore Run/Debug。
点击 OK。您现在应该会在工具栏中看到缺少的按钮。

Linux 上的按键映射冲突

在 Linux 上，某些键盘快捷键会与默认的 Linux 键盘快捷键以及常见窗口管理器（例如 KDE 和 GNOME）的键盘快捷键冲突。这些冲突的键盘快捷键可能无法在 Android Studio 中正常使用。

如需详细了解此问题（包括可能的解决办法），请参阅 IntelliJ 的错误跟踪器。

Chrome 操作系统上的界面文字太小

在 Chrome 操作系统上，文字看起来可能比以前版本中的文字小得多。若要解决此问题，请执行以下操作：

依次点击 File > Settings，打开 Settings 窗口
依次转到 Appearance & Behavior > Appearance。
选择 Use custom font。
增大字号。
在 Settings 窗口中，依次转到 Editor > Font。
增大字号。
点击 OK。

代码编辑

本部分将说明与代码编辑器相关的已知问题。

键盘输入冻结 - Linux 上的“iBus”问题

Linux 上的 iBus 守护程序与 Android Studio 之间存在一些已知的互动问题。在某些情况下，IDE 会停止响应键盘输入或开始输入随机字符。此错误由 iBus 和 XLib + AWT 之间的同步不完整而引发，并且已报告给上游的 JetBrains 和 iBus 开发者。此问题目前有三种解决方法：

解决方法 1：强制 iBus 进入同步模式。在启动 Android Studio 之前，请在命令行中运行以下命令：
```
$ IBUS_ENABLE_SYNC_MODE=1 ibus-daemon -xrd
```
解决方法 2：在 Android Studio 中停用 iBus 输入法。如需仅对 Android Studio 停用 iBus 输入法，请在命令行中运行以下命令：
```
$ XMODIFIERS= ./bin/studio.sh
```
这样做只会对 Android Studio 停用输入法，而不会影响您可能正在运行的任何其他应用。请注意，如果您在 Android Studio 处于运行状态时重启 iBus 守护程序（例如，通过运行 ibus-daemon -rd），则相当于对所有其他应用停用了输入法，并可能导致 Android Studio 的 JVM 崩溃以及出现分段错误。
解决方法 3：仔细检查快捷键设置，确保未将 Next input shortcut 设置为 Ctrl+Space，因为这也是 Android Studio 中的代码补全快捷键。Ubuntu 14.04 (Trusty) 中的默认快捷键是 Super+Space，但也可能沿用了先前版本的设置。如需检查快捷键设置，请在命令行中运行 ibus-setup 以打开“IBus Preferences”窗口。在 Keyboard Shortcuts 下，选中 Next input method。如果它已被设为 Ctrl+Space，请将其更改为 Super+Space 或您选择的其他快捷键。

项目配置

本部分将介绍与项目配置和 Gradle 同步相关的已知问题。

Gradle 同步失败：管道无效

此问题是因 Gradle 守护程序尝试使用 IPv4 而非 IPv6 引起的。

解决方法 1：在 Linux 上，将以下内容放入 ~/.profile 或 ~/.bash_profile 中：
```
export _JAVA_OPTIONS="-Djava.net.preferIPv6Addresses=true"
```
解决方法 2：在 Android Studio 的 vmoptions 文件中，将 -Djava.net.preferIPv6Addresses=true 行更改为 -Djava.net.preferIPv6Addresses=true。如需了解详情，请参阅网络 IPv6 用户指南。

Gradle 同步或 SDK 管理器中发生的“peer not authenticated”错误

这些错误的根本原因在于 $JAVA_HOME/jre/lib/certificates/cacerts 中缺少证书。如需解决此类错误，请按以下步骤操作：

如果您使用了网络代理，请尝试直接连接。如果直接连接有效，那么为了通过代理进行连接，您可能需要使用 keytool 将代理服务器的证书添加到 cacerts 文件中。
重新安装受支持且未经修改的 JDK。存在一个影响 Ubuntu 用户的已知问题，会产生空的 /etc/ssl/certs/java/cacerts。如需解决此问题，请在命令行中执行以下命令：
```
sudo /var/lib/dpkg/info/ca-certificates-java.postinst configure
```

部署

本部分将介绍有关将应用部署到已连接设备的已知问题。

macOS High Sierra 上的 Android 模拟器 HAXM

macOS High Sierra (10.13) 上的 Android 模拟器需要 HAXM 6.2.1+ 才能实现最佳的 macOS 兼容性和稳定性。不过，在 macOS 10.13 上安装 HAXM 等内核扩展的流程更为繁琐。您需要按以下方式手动允许安装内核扩展：

首先，尝试通过 SDK 管理器安装最新版本的 HAXM。
在 MacOS 中，依次转到 System Preferences > Security and Privacy。
如果您看到“System software from developer "Intel Corporation Apps" was blocked from loading”，请点击 Allow：

如需了解详情和解决方法，请参阅此 Apple 网页和问题 62395878。

Android Studio 错误地强行停止应用

使用 Android Studio 4.0.x 或 4.1 时，如果可调试的应用关闭，Android Studio 会错误地强行停止该应用。

此问题会造成以下负面影响：

使用 START_STICKY 启动的服务不会被视为粘性服务（问题 #156855259）。
已安排为在后台运行的作业和闹钟会被取消（问题 #165787618）。
强行停止事件会记录在 logcat 中（问题 #168311418）。

Apply Changes

本部分介绍与 Apply Changes 相关的已知问题。

不会应用新的应用名称

如果您重命名应用，然后尝试应用此更改，系统可能不会显示更新后的名称。若要解决此问题，请点击 Run 图标重新部署应用，然后您就会看到相应更改。

Android Runtime 中的问题抛出错误

如果您使用的是搭载 Android 8.0 或 8.1 的设备，那么在尝试应用某些类型的更改时（特别是当您使用 Kotlin 时），您可能会看到“VERIFICATION_ERROR”消息。此消息是由 Android Runtime 相关问题引起的，该问题在 Android 9.0 及更高版本中已解决。虽然该问题会导致 Apply Changes 失败，但您仍可通过点击 Run 图标重新运行应用来查看更改。不过，仍建议您将设备升级到 Android 9.0 或更高版本。

Apply Changes 失败并显示 ShellCommandUnresponsiveException

在 Android Studio 4.1 及更低版本中使用 Apply Changes 时，设备可能会卡在某个状态，无法应用任何更改。出现此问题时，Apply Changes 会失败并显示 ShellCommandUnresponsiveException。

若要解决此问题，请运行以下 adb 命令：

adb shell rm -fr /data/local/tmp/.studio

使用 android:sharedUserId 时无法应用更改

如果您尝试更改尚未部署到正在运行的应用的类，并且您的应用是通过以下任一方式配置的，Apply Changes 将失败：

您的应用使用共享的 android:sharedUserId 与另一个应用共享数据。
您的应用使用共享的 android:sharedUserId 和 android:process 与另一个应用在同一个进程中运行。

当 Apply Changes 由于这个问题而失败时，Android Studio 会显示以下消息：

Changes were not applied. JVMTI error: UNKNOWN_JVMTI_ERROR

若要在 Android Studio 3.5 中解决此问题，请点击 Run 图标重新部署应用，然后您就会看到相应更改。

调试和测试

本部分将介绍与调试和测试应用相关的已知问题。

从 Android Studio 运行时，JUnit 测试在类路径中找不到资源

如果您的 Java 模块使用了特定的资源文件夹，那么从 IDE 运行测试时将找不到这些资源。您可以从命令行使用 Gradle 运行测试，也可以从 IDE 执行 Gradle check 任务。如需了解详情，请参阅问题 64887。

出现此问题的原因是，从 IntelliJ 13 起，您只能将一个文件夹用作类路径。IntelliJ 的构建工具会将所有资源复制到该 build 文件夹中，但 Gradle 不会复制这些资源。

解决方法 1：从 IDE 运行 Gradle check 任务，而不是运行单元测试。
解决方法 2：更新构建脚本以手动将资源复制到 build 文件夹中。如需了解详情，请参阅此处的第 13 条评论。

运行 JUnit 测试可能会编译两次代码

创建新项目时，系统可能会在 Make 和 Gradle-aware Make 这两个“发布前”步骤中创建模板 JUnit 配置。然后，系统会将此配置传播到所有已创建的 JUnit 运行配置。

若要为当前项目修复此问题，请依次点击 Run > Edit Configurations，然后将默认的 JUnit 配置更改为仅包含 Gradle-aware Make 步骤。
若要为今后的所有项目解决此问题，请依次点击 File > Close Project。您应该会看到欢迎屏幕。然后，依次点击 Configure > Project Defaults > Run Configurations，并将 JUnit 配置更改为仅包含 Gradle-aware Make 步骤。

某些测试运行配置无效

右键点击某个测试方法时，并非所有可用的运行配置都有效。具体而言，以下配置无效：

Gradle 运行配置（其图标为 Gradle 徽标）无效。
JUnit 运行配置（其图标不带绿色的 Android）不适用于插桩测试（此类测试无法在本地 JVM 上运行）。

Android Studio 还会记住在给定上下文中创建的运行配置（例如，右键点击特定类或方法），并且以后不会为您提供在其他配置中运行的选项。若要修复此问题，请依次点击 Run > Edit Configurations，然后移除错误创建的配置。

调试原生代码时添加 Java 断点

当您的应用在原生代码中的断点处暂停时，Auto 和 Dual 调试程序可能无法立即识别您设置的新 Java 断点。若要避免此问题，请在启动调试会话之前或在 Java 断点处暂停应用时添加 Java 断点。如需了解详情，请参阅问题 229949。

退出原生调试程序

使用 Auto 或 Dual 调试程序调试 Java 代码和原生代码时，如果您通过 Java 代码逐步执行原生函数（例如，调试程序在调用原生函数的某行 Java 代码处暂停执行，并且您点击 Step Into 图标）并且希望返回到 Java 代码，请点击 Resume Program 图标（而非 Step Out 图标或 Step Over 图标）。您的应用进程仍将处于暂停状态，因此请点击 your-module-java 标签页中的 Resume Program 图标来将其恢复。如需了解详情，请参阅问题 224385。

性能剖析器

本部分将说明性能剖析器的已知问题。

System Trace 界面中缺少标签

在缩放比例为 125% 和 175% 的 Windows 计算机上，标签可能会从 System Trace 界面的某些元素（包括线程活动时间轴）中消失。若要解决此问题，请将您显示屏的缩放比例更改为除 125% 或 175% 以外的任何值。

此问题已在 Android Studio 4.2 中修复。

原生内存性能分析器：在应用启动过程中无法进行性能剖析

原生内存性能分析器目前在应用启动过程中不可用。此选项会在即将发布的版本中提供。

解决方法之一是，您可以使用 Perfetto 独立命令行性能剖析器来捕获启动性能剖析记录。

CPU 性能剖析器中的超时错误

如果您选择采样 Java 方法或跟踪 Java 方法配置，则可能会在 Android Studio CPU 性能剖析器中遇到“停止记录失败”错误。这些是常见的超时错误，尤其是当您在 idea.log 文件中看到以下错误消息时：

Wait for ART trace file timed out

超时错误对所跟踪方法的影响往往大于所采样方法，对较长时间记录的影响往往大于较短时间的记录。作为临时解决方法，尝试较短时间的记录以查看错误是否消失可能会很有帮助。

如果您在使用性能剖析器时遇到超时问题，请提交错误，在提交内容中附上设备品牌/型号以及来自 idea.log 和 logcat 的所有相关条目。

调试或性能剖析时出现 adb 异常

使用 Platform Tools 29.0.3 时，原生调试和 Android Studio 性能剖析器可能无法正常工作，并且如果您依次选择 Help > Show Log，可能会在 idea.log 文件中看到“AdbCommandRejectedException”或“Failed to connect port”。将 Platform Tools 升级到 29.0.4 或更高版本可以解决这两个问题。

如需升级 Platform Tools，请执行以下操作：

依次点击 Tools > SDK Manager 或点击工具栏中的 SDK Manager 图标，从 Android Studio 打开 SDK 管理器。

点击 Android SDK Platform-Tools 旁边的复选框，使其显示复选标记。左侧列中应会显示下载图标。

点击 Apply 或 OK。

Android Gradle 插件的已知问题

本部分将介绍最新的稳定版 Android Gradle 插件中存在的已知问题。

缺少清单类

如果您的应用在其清单中定义自定义权限，Android Gradle 插件通常会生成 Manifest.java 类，用于以字符串常量的形式添加您的自定义权限。该插件会将此类与您的应用打包在一起，以便于您在运行时更轻松地引用这些权限。

目前，无法在 Android Gradle 插件 3.6.0 及更高版本中生成清单类。如果您使用此版本的插件构建应用，并且该应用引用了清单类，您可能会看到 ClassNotFoundException 异常。若要解决此问题，请执行以下某项操作：

通过完全限定名称引用自定义权限。例如，"com.example.myapp.permission.DEADLY_ACTIVITY"。

定义您自己的常量，如下所示：

public final class CustomPermissions {
  public static final class permission {
    public static final String DEADLY_ACTIVITY="com.example.myapp.permission.DEADLY_ACTIVITY";
  }

对使用回车符 (CR) 命名的文件签名

JAR 签名（v1 方案）不支持包含回车符 (CR) 的文件名。（请参阅问题 #63885809）。

API 变更

在 Android Gradle 插件 3.0.0 及更高版本引入的 API 变更中，部分功能被移除，因此您的现有 build 可能会出现异常。插件的更高版本可能会引入新的公共 API 来替代失效的旧功能。

在构建时可能无法正常修改变体输出

新插件不支持使用 Variant API 来操纵变体输出，但仍然支持使用该 API 处理某些简单任务，例如在构建时更改 APK 名称，具体如下所示：

// If you use each() to iterate through the variant objects,
// you need to start using all(). That's because each() iterates
// through only the objects that already exist during configuration time—
// but those object don't exist at configuration time with the new model.
// However, all() adapts to the new model by picking up object as they are
// added during execution.
android.applicationVariants.all { variant ->
    variant.outputs.all {
        outputFileName = "${variant.name}-${variant.versionName}.apk"
    }
}

不过，涉及访问 outputFile 对象的复杂任务已不再受支持。这是因为在配置阶段不会再创建专门针对特定变体的任务。这会导致插件不能预先了解所有的输出，但这也意味着将会缩短配置时间。

manifestOutputFile 不再可用

processManifest.manifestOutputFile() 方法不再可用，您在调用该方法时将会遇到以下错误：

A problem occurred configuring project ':myapp'.
   Could not get unknown property 'manifestOutputFile' for task ':myapp:processDebugManifest'
   of type com.android.build.gradle.tasks.ProcessManifest.

您可以调用 processManifest.manifestOutputDirectory() 来获取包含所有已生成清单的目录路径，而无需调用 manifestOutputFile() 来获取每个变体的清单文件。然后您可以找到相应清单，并对该清单应用您的逻辑。以下示例将在清单中动态更改版本代码：

android.applicationVariants.all { variant ->
    variant.outputs.all { output ->
        output.processManifest.doLast {
            // Stores the path to the maifest.
            String manifestPath = "$manifestOutputDirectory/AndroidManifest.xml"
            // Stores the contents of the manifest.
            def manifestContent = file(manifestPath).getText()
            // Changes the version code in the stored text.
            manifestContent = manifestContent.replace('android:versionCode="1"',
                    String.format('android:versionCode="%s"', generatedCode))
            // Overwrites the manifest with the new text.
            file(manifestPath).write(manifestContent)
        }
    }
}

已修复的已知问题

本部分介绍最新版本中已经修复的已知问题。如果您遇到所述的任何问题，请将 Android Studio 更新为最新稳定版或预览版。

Android Studio 4.1 中修复的问题

重启以应用之前 IDE 版本中的内存设置：更新 Android Studio 后，您需要重启 Android Studio 才能应用从之前 IDE 版本中迁移过来的任何内存设置。

Android Studio 3.6 中已修复的问题

LineageOS 上的 APK 安装错误：将应用部署到运行某些版本的 LineageOS 或 CyanogenMod 的设备可能会失败，并抛出 INSTALL_PARSE_FAILED_NOT_APK 异常。

在 Android Studio 3.6 Beta 1 及更高版本上，当您将应用部署到 LineageOS 或 CyanogenMod 设备时，IDE 会通过执行完整的应用安装来处理此异常，这可能会导致部署时间变长。

Android Studio 3.5.2 中已修复的问题

XML 代码样式损坏：在修改 XML 代码时，如果从菜单栏中依次选择 Code > Reformat Code，IDE 会应用不正确的代码样式。

Android Studio 3.3.1 中已修复的问题

扫描基于 C++ 的项目时出现内存不足错误：如果 Gradle 扫描的项目在同一驱动器上的多个位置都有 C++ 代码，则扫描会涵盖这些位置的首个共通目录下的所有目录。扫描大量目录和文件可能会导致出现内存不足错误。

如需详细了解此问题，请参阅与该问题相关的错误。