Kotlin / Android 开发环境配置 - 码剑客

配置 Kotlin 与 Android 开发环境：Android Studio、cmdline-tools 与 SDK、ANDROID_HOME、Gradle 换源、模拟器与 adb 调试、常见报错排查。

Kotlin 2.x / AGP 8.x更新于 2026-10-29共 29 条

安装与版本管理

Windows 安装 Android Studio，首次启动向导会自动下载 SDK 与模拟器

winget install Google.AndroidStudio

向导中务必选中 Android SDK、SDK Platform-Tools 与一个 API 级别

macOS 用 Homebrew、Ubuntu 用 snap 安装 Android Studio

# macOS
brew install --cask android-studio
# Ubuntu
sudo snap install android-studio --classic

用命令行安装 platform-tools、指定 API 平台与构建工具

sdkmanager --list
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

sdkmanager 位于 cmdline-tools/latest/bin，需先加入 PATH

安装模拟器系统镜像，用于创建 AVD

sdkmanager --install "system-images;android-34;google_apis;x86_64"

AGP 8.x 需要 JDK 17，单独装一份供 Gradle 使用

winget install EclipseAdoptium.Temurin.17.JDK

镜像源与代理

在 settings.gradle.kts 的 pluginManagement 中加阿里云仓库，加速插件下载

pluginManagement {
  repositories {
    maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
    google()
    mavenCentral()
  }
}

在 settings.gradle.kts 中统一声明依赖仓库，避免各模块重复配置

dependencyResolutionManagement {
  repositories {
    maven { url = uri("https://maven.aliyun.com/repository/public") }
    google()
    mavenCentral()
  }
}

查看全局 Gradle 参数，可在此设置代理与 JVM 内存

# Windows
type %USERPROFILE%\.gradle\gradle.properties
# macOS / Linux
cat ~/.gradle/gradle.properties

写入 ~/.gradle/gradle.properties，让 Gradle 下载依赖时走代理

systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=7890
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=7890

提高 Gradle 堆内存并固定编码，缓解构建卡死与乱码

org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8

环境变量

设置 ANDROID_HOME 并把 platform-tools 加入 PATH，adb 才能直接调用

# Windows
setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools"
# macOS / Linux
echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc

确认变量指向真实的 SDK 目录（内含 platforms、build-tools）

echo %ANDROID_HOME%
# macOS / Linux
echo $ANDROID_HOME

指定 Gradle 使用的 JDK 17，避免 AGP 版本校验失败

# Windows PowerShell
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-17", "User")

验证 adb 可用并列出已连接设备或模拟器

adb version
adb devices

创建工程与验证

确认 JDK 与 Gradle Wrapper 版本，工程统一用 wrapper 而不是本机 gradle

java -version
./gradlew --version

列出并创建 AVD 模拟器，也可在 Android Studio 的 Device Manager 中操作

avdmanager list avd
avdmanager create avd -n pixel_34 -k "system-images;android-34;google_apis;x86_64"

命令行启动模拟器，无界面环境可加 -no-window

emulator -list-avds
emulator -avd pixel_34

构建 Debug APK，产物在 app/build/outputs/apk/debug 下

./gradlew assembleDebug

安装到设备并直接启动主 Activity

./gradlew installDebug
adb shell am start -n com.example.app/.MainActivity

单独使用 Kotlin 编译器时验证版本；Android 工程一般由 Gradle 插件管理

kotlinc -version

编辑器与插件

VS Code 安装 Kotlin 语法支持与 Gradle 任务面板

code --install-extension mathiasfrohlich.kotlin
code --install-extension vscjava.vscode-gradle

纯 Kotlin/JVM 项目可用 IntelliJ IDEA 社区版，Android 开发仍推荐 Android Studio

winget install JetBrains.IntelliJIDEA.Community

只看崩溃日志，快速定位运行时异常堆栈

adb logcat -s AndroidRuntime

常见问题排查

提示未接受许可协议导致构建失败时，逐条确认许可

sdkmanager --licenses

设备列表为空或显示 offline 时重启 adb 服务

adb kill-server
adb start-server
adb devices

Gradle 守护进程状态异常或构建卡死时停掉守护进程后重试

./gradlew --stop
./gradlew clean assembleDebug --no-daemon

高危

依赖损坏时删除模块缓存，下次构建会重新下载

rm -rf ~/.gradle/caches/modules-2

排查依赖冲突，定位重复或版本不一致的库

./gradlew :app:dependencies --configuration debugRuntimeClasspath

让真机/模拟器流量走电脑代理，调试抓包时使用

adb shell settings put global http_proxy 127.0.0.1:7890