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

Android Studio 的已知问题

渲染 Compose 预览时出错

从 Android Studio Chipmunk 开始，如果您在问题面板中看到 java.lang.NoSuchFieldError: view_tree_saved_state_registry_owner 或 java.lang.ClassNotFoundException: androidx.savedstate.R$id，请务必在模块中添加对 androidx.lifecycle:lifecycle-viewmodel-savedstate 的 debugImplementation 依赖项。

如果您在问题面板中看到 java.lang.NoSuchFieldError: view_tree_lifecycle_owner，请务必在模块中添加对 androidx.lifecycle:lifecycle-runtime 的 debugImplementation 依赖项。

如果您在问题面板中看到 java.lang.NoClassDefFoundError: Could not initialize class androidx.customview.poolingcontainer.PoolingContainer 或 java.lang.NoClassDefFoundError: androidx/customview/poolingcontainer/PoolingContainerListener，请务必在模块中添加对 androidx.customview:customview-poolingcontainer 的 debugImplementation 依赖项。

对密钥和密钥库使用不同的密码时出错

从 4.2 版本开始，Android Studio 现在将在 JDK 11 上运行。此变更会导致与签名密钥相关的底层行为发生变更。

在您依次进入 Build > Generate Signed Bundle / APK 并尝试为 app bundle 或 APK 配置应用签名时，如果对密钥和密钥库输入不同的密码，就可能会导致以下错误：

Key was created with errors:
Warning: Different store and Key passwords not supported for PKCS12 Key stores

如需解决此问题，请为密钥和密钥库输入相同的密码。

安装 4.2 版本后，Android Studio 无法启动

Studio 会尝试导入之前版本的 .vmoptions 并对其进行清理，以便与 JDK 11 使用的垃圾回收器配合使用。如果此进程失败，对于在 .vmoptions 文件中设置了自定义虚拟机选项的用户，Android Studio 可能不会启动。

为了解决此问题，我们建议在 .vmoptions 中注释掉自定义选项（使用“#”字符）。.vmoptions 文件位于以下位置：

Windows

C:\Users\YourUserName\AppData\[Local|Roaming]\Google\AndroidStudio4.2\studio64.exe.vmoptions

macOS

~/Library/Application Support/Google/AndroidStudio4.2/studio.vmoptions

Linux

~/.config/Google/AndroidStudio4.2/studio64.vmoptions

使用 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 应该能解决此问题。

Linux 上的按键映射冲突

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

ChromeOS 上的界面文字较小

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

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

代码编辑

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

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

Linux 上的 iBus 守护程序与 Android Studio 之间存在一些已知的互动问题。在某些情况下，IDE 会停止响应键盘输入或开始输入随机字符。此 bug 由 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.preferIPv4Addresses=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
```

部署

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

[仅限 Mac OS] 由于保存在 `/System/Volumes/Data` 下的项目的 Gradle 文件监控存在问题，因此系统无法执行增量更新

Gradle 问题 18149 会影响 Android Gradle 插件版本 7.0 及更高版本，因为它们需要 Gradle 版本 7.0 及更高版本。从 Gradle 7.0 开始，文件监控功能默认处于启用状态。如果您使用的是 Mac OS 并且项目保存在 /System/Volumes/Data 下，Gradle 文件监控功能将无法正确跟踪文件更改。这会使构建系统看不到任何文件更改，因此无法更新 APK。此时，增量部署代码将不执行任何操作，因为本地 APK 状态与设备上的状态相同。

如需解决此问题，您应将项目的目录移动到用户目录，即 /Users/username 下。然后，构建系统会通过 Gradle 文件监控功能正确收到有关文件更改的通知，并成功应用增量更改。

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：

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 或更高版本。

调试和测试

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

从 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 图标来将其恢复。

原生调试程序在加载库时挂起

在升级到 Android Studio 4.2 及更高版本后首次使用原生调试程序时，原生调试程序可能会在从 Android 设备加载库时停止响应。这是一项棘手的问题，即使您停止并重启调试程序，也会继续出现此问题。如需解决此问题，请在 $USER/.lldb/module-cache/ 删除 LLDB 缓存。

原生调试程序崩溃并显示“Debugger process finished with exit code 127”

基于 Linux 的平台在启动原生调试程序时会发生此错误。这表示原生调试程序所需的某个库未安装在本地系统上。缺少的库的名称可能已输出到 idea.log 文件中。若未输出，您可以使用终端进入 Android Studio 安装目录，然后执行 bin/lldb/bin/LLDBFrontend --version 命令行以查明缺少哪些库。通常，缺少的库是 ncurses5，因为某些最新的 Linux 发行版已升级到 ncurses6。

性能分析器

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

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

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

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

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

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

Wait for ART trace file timed out

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

如果您在使用性能分析器时遇到超时问题，请提交 bug，在提交内容中附上设备品牌/型号以及来自 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。

插件阻止“Build Output”窗口正常运行

使用 CMake simple highlighter 插件会阻止内容显示在“Build Output”窗口中。build 会运行，“Build Output”标签页会显示，但系统不会输出任何内容（问题 204791544）。

安装顺序阻碍启动

如果先安装新版本的 Android Studio，再安装旧版本的 Android Studio，可能会导致旧版本无法启动。例如，如果您先安装 Canary 版 Android Studio，然后尝试安装并启动稳定版本，则稳定版本可能无法启动。在此类情况下，您必须清除缓存，才能启动稳定版本（旧版本）。在 macOS 上，如需清除缓存，请删除 Library/ApplicationSupport/Google/AndroidStudioversion_number 目录。在 Windows 上，如需清除缓存，请使用磁盘清理功能。

Espresso 测试记录器无法与 Compose 配合使用

Espresso 测试记录器不适用于包含 Compose 的项目。如需为包含 Compose 的项目创建界面测试，请参阅测试 Compose 布局。

Logcat 快捷键与非英语键盘布局冲突

如果您使用的是非英语键盘布局，则默认的 Logcat 键盘快捷键可能会与布局冲突，导致您在 Android Studio 中编辑文本时无法输入某些字符。如要解决此问题，请删除或重新映射有冲突的 Logcat 按键映射。如需在 Android Studio 中修改 Logcat 按键映射，请依次前往 Android Studio > Settings > Keymap，然后在按键映射列表中搜索 Logcat。如需了解详情，请参阅问题 263475910。

此问题将在 Android Studio Electric Eel Patch 1 中通过移除 Logcat 快捷键来解决。

Android Gradle 插件的已知问题

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

系统不会对所有动态功能库依赖项进行 lint 检查

在设置了 checkDependencies = true 的情况下从应用模块运行 lint 时，系统不会检查动态功能库依赖项，除非这些库依赖项同时也是应用依赖项（问题 191977888）。解决方法之一是，您可以在这些库上运行 lint 任务。

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

JAR 签名（v1 方案）不支持包含回车符的文件名（问题 63885809）。

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

新插件不支持使用 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)
        }
    }
}

AGP 7.3.0 AIDL 支持和 Kotlin 1.7.x 的问题

在 Kotlin 1.7.x 中将 AGP 7.3.0 与 KAPT 搭配使用会导致特定 build 变体的 AIDL 源代码集被移除。您仍然可以使用其他 AIDL 源代码集，包括 main/、build 类型、产品变种和产品变种组合的 AIDL 源代码集。如果您需要使用针对特定变体的 AIDL 源代码集，请继续使用 Kotlin 1.6.21。

修复的已知问题

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

Android Studio 2021.1.1 中已修复的问题

缺少 lint 输出：lint 任务的状态为 UP-TO-DATE 时无输出到 stdout 的 lint 文本输出（问题 191897708）。已在 AGP 7.1.0-alpha05 中修复。
对使用 Hilt 插件的应用项目进行单元测试时出现问题：单元测试类路径包含非插桩应用类，这意味着，运行单元测试时，Hilt 不会插桩应用类来处理依赖项注入（问题 213534628）。已在 AGP 7.1.1 中修复。

Android Studio 2020.3.1 中已修复的问题

Kotlin 项目中的 lint 异常：设置了 checkDependencies = true 的 Kotlin 项目可能会遇到 null 指针异常或错误（问题 158777858）。

Android Studio 4.2 中已修复的问题

IDE 在 macOS Big Sur 上冻结：Android Studio 4.1 可能会在您打开对话框时冻结。

Android Studio 4.1 中修复的问题

重启以应用之前 IDE 版本中的内存设置：更新 Android Studio 后，您需要重启 Android Studio 才能应用从之前 IDE 版本中迁移过来的任何内存设置。
默认情况下，不再生成具有自定义权限字符串的清单类：如果您要生成该类，请设置 android.generateManifestClass = true。

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 中已修复的问题