尧图网站建设 
很多朋友想学 Kotlin 开发 Android app第一反应是先去啃语法、刷教程结果刷了一个月代码看得懂但一打开 Android Studio 还是不知道从哪儿下手。我见过太多这样的例子所以我一直建议第一步永远是先把一个能跑的工程建立起来让代码真正跑在模拟器或者手机上。本篇文章就是这套系列教程的第一篇目标非常明确——用 Kotlin 建立 Android 工程理解 Android Studio 生成出来的每个关键文件然后亲手写一个最简界面并运行起来。适合完全零基础的新手也适合以前写 Java、现在想切 Kotlin 的老开发。1. 为什么用Kotlin建Android工程先搞懂官方模板的分岔1.1 Kotlin成为Android首选语言对“建工程”这件事意味着什么在 2017 年 Google I/O 上Google 宣布 Kotlin 成为 Android 开发的一级语言到了 2019 年官方直接宣布Kotlin First所有官方文档、示例代码、新库优先为 Kotlin 适配。这个变化不是喊口号它实打实地改变了我们“建工程”时面对的默认选项。最直接的感受就是现在你打开 Android Studio 新建项目大多数模板的默认语言已经变成 Kotlin生成的代码也都是 Kotlin 风格。以前 Java 时代建工程时还要手动加 Kotlin 插件、配置 kotlin-stdlib 依赖现在这些步骤全部被工具链消化掉了。你只需要在向导里选一下语言Android Studio 会自动帮你把 Kotlin 插件挂到 Gradle 构建脚本里把标准库依赖写进配置。这意味着建立工程的第一个门槛已经消失剩下的就是理解“工程被建出来之后里面到底是什么”。我见过不少从 Java 转过来的朋友下意识还用 Java 的思维套 Kotlin看到class MainActivity : AppCompatActivity()时第一反应是“冒号是什么”。这里提前说一句Kotlin 用冒号表示继承替代 Java 里的extends关键字后面在解读 MainActivity 的时候还会再遇到。1.2 Empty Views Activity 与 Empty Activity 的选择XML 还是 Compose现在的 Android Studio 新建项目时最容易让人纠结的是模板选择。最常看到的两个模板是Empty Views Activity基于传统 View 体系界面写在res/layout下的 XML 文件里Kotlin 代码通过setContentView()加载布局。Empty Activity基于 Jetpack Compose界面直接用 Kotlin 代码写可组合函数没有 XML 布局文件偏向纯声明式 UI。很多教程里把这两个模板混着用读者就被绕晕了。我给新手的建议非常明确第一篇文章、第一个工程优先选 Empty Views Activity。原因有两个。第一传统 View XML 的模型直观界面是“一个布局文件 一个 Activity”你可以在 XML 里看到控件、属性也可以在 Kotlin 代码里用findViewById或 ViewBinding 找到它们这条链路符合人类理解界面的直觉。Compose 虽然写起来更简洁但它把“界面长什么样”和“界面怎么响应用户”都打散到函数里心智模型对新手来说偏抽象。第二传统 View 体系下的知识点后续学 Android 四大组件、样式主题、资源系统时会反复用到这部分基础打得牢再学 Compose 时反而更快。1.3 先建工程后学语法的学习节奏有人会问Kotlin 语法都没学怎么建工程我的回答是正因为你没学才更要先把工程跑起来。建立 Android 工程本质上是在告诉你三条信息代码文件放在哪里构建脚本写在哪里资源文件怎么组织。这些内容和 Kotlin 语法本身没多大关系但你有了一个可视化的“容器”之后再回去看val、var、函数声明、空安全就能立刻在一个真实工程里做实验。我自己带人的经验是先建工程、跑通界面、改几个文字、加一个按钮这一套流程走完新手对 Kotlin 的接受速度会明显加快。原因很简单语法是砖头工程是房子你手里得有房子才知道砖头往哪儿砌。2. 环境前置Android Studio、JDK 与 SDK 的版本协同2.1 新版Android Studio自带JDK别再手动折腾JAVA_HOME很多老教程会先让你去下载 JDK 8然后配置JAVA_HOME环境变量再安装 Android Studio。这套流程放在五年前没问题但现在反而会给自己挖坑。新版 Android Studio比如 2022 年之后的版本已经内置了 JetBrains Runtime本质就是一个 JDK新建工程时 Gradle 直接用它来跑构建你不需要、甚至不应该再去单独下载 JDK。如果你在 macOS 上单独装了 JDK 8反而可能出现“Android Gradle Plugin 需要 JDK 17但你用的是 JDK 8”这类版本冲突。正确的做法是安装 Android Studio 后打开File - Settings - Build, Execution, Deployment - Build Tools - Gradle把Gradle JDK设置为Embedded JDK或jbr-17之类的新版本。这里最常见的问题就是 Gradle JDK 被设成旧版本导致构建时报Unsupported class file major version改回内置 JDK 就能解决。2.2 compileSdk、minSdk与AGP版本之间的对应关系建立工程之前有必要先理清几个会一直陪着你开发的关键参数compileSdk、minSdk、targetSdk以及它们和 Android Gradle PluginAGP、Gradle 版本之间的关系。compileSdk编译时使用的 SDK 版本决定了你能调用哪些系统 API。新版 Android Studio 创建工程时会给一个推荐值比如 API 35。minSdk最低支持的 Android 版本低于这个版本的手机装不上你的 app。targetSdkapp 声明自己针对哪个版本做过兼容适配系统会据此决定是否开启某些行为变更。版本之间不是随便配的AGP 对 Gradle 和 JDK 都有最低要求。我用一张表总结常见的对应关系Android Studio 版本AGP 版本最低 Gradle 版本建议 JDKFlamingo 2022.28.08.0JDK 17Hedgehog 2023.18.28.2JDK 17Koala 2024.18.58.7JDK 17正常情况下Android Studio 会自动为你匹配好对应版本你不需要背这张表。但当你面向搜索引擎查错时看到的报错信息往往就藏在这些版本对应关系里。比如Minimum supported Gradle version is X.X.X翻译过来就是“你的 Gradle 太旧了升级工程里 gradle-wrapper.properties 指定的版本”。2.3 SDK Manager 里哪些组件必须装Android Studio 第一次启动后会提示你安装 Android SDK。打开Settings - Languages Frameworks - Android SDK你会看到一堆组件别慌真正必装的就这几项SDK Platform对应你compileSdk指定的版本比如 API 35。Android SDK Build-Tools编译打包过程中负责生成资源、DEX 字节码的工具集。Android SDK Platform-Tools包含 adbAndroid Debug Bridge真机调试、Logcat 输出都靠它。至于系统镜像System Image是创建模拟器时才需要下载的不等同于 SDK 必装项。首次安装时建议把 SDK Platform 和 Build-Tools 的对应版本勾选好能避免后面构建时出现各种“找不到 resource”或者“Failed to find Build Tools revision”。2.4 环境阶段的典型报错找不到SDK、构建工具缺失环境没配好时报错会很直接但新手常被吓住。我挑两个出现频率最高的说一下。一个是SDK location not found. Define a valid SDK location with an ANDROID_HOME environment variable or by setting the sdk.dir。这通常发生在你从别人那里拷贝工程、或者打开了没有 SDK 配置的工程时。解决办法在工程根目录的local.properties文件里写一行sdk.dir/你的SDK路径。另一个是Failed to find Build Tools revision 30.0.3意思是工程要求的构建工具版本本地没装。解决办法有两个打开 SDK Manager 勾选对应版本安装或者把工程里build.gradle.kts的buildToolsVersion改成本地已安装的版本。比较推荐第一个因为随意降低构建工具版本可能引入兼容问题。3. 创建工程全流程从New Project到一个能跑的App3.1 模板选择与项目信息填写环境准备好之后正式建工程。打开 Android Studio点击New Project进入模板选择界面。按前面说的左侧选Phone and Tablet右侧选Empty Views Activity点击Next。接下来是项目信息表单需要填四项。Name应用名称也是工程名称。比如KtDemo。注意不要用中文和空格因为工程名会成为目录名目录名里带空格在某些构建工具中会出奇怪问题。Package name应用包名后面单独说。Save location工程保存路径建议放在一个路径简单、没有中文的目录下。Language这里下拉框选Kotlin。Minimum SDK最低支持版本建议先选API 24。最后点击FinishAndroid Studio 会开始创建 Gradle 工程并执行首次同步。第一次同步通常会持续几分钟因为要下载 Gradle 发行版和依赖库取决于网络状况。3.2 包名Package Name为什么必须遵守反域名规则包名是 Android 应用在整个系统里的唯一身份标识。它采用反向域名规则比如com.example.ktdemo。为什么要反域名因为域名是全局唯一的把域名倒过来当命名空间能最大程度避免不同公司的应用包名冲突。包名里有几个潜规则需要注意不能以数字开头每一段不能包含连字符只能使用字母、数字和下划线。常见的反面例子是com.example.my-app连字符会让编译器直接报错。包名还决定了一件事你的 R 类和 BuildConfig 类会生成在这个包名下。所以在工程建好之后你会在app/src/main/java/com/example/ktdemo/目录下看到MainActivity.kt这个目录结构必须和包名保持一致。Android Studio 按包名帮你建好目录如果你在向导里手动修改了包名目录会自动跟着调整不需要自己建文件夹。3.3 Minimum SDK的选择逻辑很多新手对Minimum SDK没概念以为越低越好。实际上minSdk设得太低意味着你要在代码里兼容很老的系统行为比如运行时权限、存储分区这些 API 差异每一样都要写兼容逻辑设得过高又会丢掉使用老手机的潜在用户。我的建议是自己学习的话选API 24对应 Android 7.0。理由很简单从 API 24 开始多数国产 app 的最低支持线也在这个位置你在网上找到的第三方库也基本都覆盖了这个版本。而且 API 24 已支持最新的 Material Design 组件界面效果不会显得老旧。如果你做的应用只给自己用、只在最新的测试机上跑那也可以选 API 33、API 34 这类更高的版本省掉很多兼容性判断但就要接受老设备装不上的代价。这个选择的本质是“开发成本”和“覆盖范围”之间的博弈没有绝对正确只有合不合适。3.4 构建配置面板Kotlin DSL 与 Groovy DSL新版 Android Studio 创建工程时构建脚本默认用Kotlin DSL文件后缀是.kts。在向导的底部你可能看到类似“Build configuration language”的选项里面有Kotlin DSL (recommended)和Groovy DSL两个选项。两者只是写法不同能力是一样的。Kotlin DSL 的好处是脚本本身是 Kotlin 代码有类型检查IDE 补全能力强写错配置立刻能标红。Groovy DSL 是老一代方案语法更自由但靠运行时执行很多错误要等构建时才暴露。对新手来说不用纠结保持默认的 Kotlin DSL 就好。最开始的阶段你甚至不需要主动去改这些脚本只要知道“工程的构建规则写在这里”就够了。4. 读懂生成的工程骨架Gradle脚本、Manifest与第一个Kotlin文件4.1 新版工程的Gradle三件套settings、build与libs.versions.toml建好工程后第一件事不是马上写代码而是花 10 分钟把整个工程目录过一遍。先看根目录下的 Gradle 相关文件这是整个工程的构建引擎。我将关键文件的作用整理成了表格文件作用settings.gradle.kts声明仓库地址和包含哪些模块。默认只有一个:app模块仓库一般配置google()、mavenCentral()build.gradle.kts根目录声明所有模块共用的插件版本比如 AGP 版本、Kotlin 插件版本。这里不直接应用插件只是声明build.gradle.ktsapp目录app 模块的具体构建配置包括compileSdk、minSdk、依赖库列表gradle/libs.versions.toml版本目录把插件和依赖的版本号集中管理起来比如 AGP 版本、Kotlin 版本、核心库版本gradle-wrapper.properties指定 Gradle 发行版的具体版本是工程自带 Gradle 的入口新手最容易忽略的是libs.versions.toml。不知道你有没有遇到过这种场景项目里同一款依赖的版本在多处出现升级时漏改一处构建就报错。版本目录就是为了解决这个问题它把版本号统一收拢到一个文件里后面在build.gradle.kts中用libs.xxx.yyy的方式引用。看别人的开源项目时如果不懂这个机制会看不懂 build 脚本里的写法所以提前认识它很重要。4.2 AndroidManifest.xml应用的门面配置接着看app/src/main/AndroidManifest.xml。这个文件是 Android 应用的“门面登记表”系统要知道你是谁、有哪些页面、能干什么全靠它。一个最简清单长这样manifest xmlns:androidhttp://schemas.android.com/apk/res/android application android:labelKtDemo android:iconmipmap/ic_launcher android:themestyle/Theme.KtDemo activity android:name.MainActivity android:exportedtrue intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter /activity /application /manifest这里有两个信息量最大的点。第一个是android:exportedtrue它表示这个 Activity 可以被其他应用唤起。从 Android 12 开始如果 Activity 带有LAUNCHER启动类别exported必须显式声明为 true否则安装或启动时会报错。第二个是intent-filter里的MAINLAUNCHER它告诉系统“应用图标点开后第一个打开的是 MainActivity”。4.3 MainActivity.kt 与隐藏的R类再来看MainActivity.kt这是整个工程里唯一的主力 Kotlin 文件package com.example.ktdemo import android.os.Bundle import androidx.appcompat.app.AppCompatActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) } }逐行拆解class MainActivity : AppCompatActivity()声明了一个继承自AppCompatActivity的类保证在低版本 Android 上也有兼容的主题和 Fragment 支持。override fun onCreate是生命周期入口savedInstanceState: Bundle?后面的问号表示这个参数可以为空这是 Kotlin 空安全设计的体现。R.layout.activity_main引用的是项目里res/layout/activity_main.xml这个布局文件。看到R类了吗它是在构建过程中自动生成的。你每往res目录放一个文件构建时就会在 R 类里生成对应的资源 ID。你不需要关心 R 类的源码长在哪只需要记住一个规律资源文件里有什么R 类就有什么引用。4.4 res资源目录layout、values、drawable、mipmap的职责Android 工程里所有非代码资源都放在app/src/main/res/下按目录区分类型。搞清楚每个目录的职责能帮你少踩很多资源引用错误的坑。目录存放内容常见文件示例layout/界面布局文件控制页面内容摆放activity_main.xmlvalues/字符串、颜色、尺寸、主题等资源strings.xml、colors.xml、themes.xmldrawable/位图、矢量图、形状选择器ic_launcher_background.xmlmipmap/应用图标按不同屏幕密度分文件夹ic_launcher.webp新手常犯的错误是在代码里硬编码文字比如textView.text 你好。正确做法是把文字写进values/strings.xml然后通过string/xxx引用。这样做的好处是适配多语言时只需要在values-en目录下再写一个同名字符串无需改动代码而且官方 lint 会提示硬编码问题。类似地颜色尽量用color/xxx尺寸用dimen/xxx从一开始养成资源化习惯后面做深色模式、屏幕适配会省很多事。5. 手写第一块Kotlin界面从XML布局到真机运行的闭环5.1 在activity_main.xml里搭一个简单的界面工程建好之后默认的activity_main.xml是一个空的布局。现在我们把它改成最简单的交互界面一行文字加一个按钮。打开app/src/main/res/layout/activity_main.xml用 LinearLayout 替换默认布局?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightmatch_parent android:orientationvertical android:gravitycenter TextView android:idid/tvHello android:layout_widthwrap_content android:layout_heightwrap_content android:textHello Kotlin android:textSize24sp / Button android:idid/btnClick android:layout_widthwrap_content android:layout_heightwrap_content android:layout_marginTop16dp android:text点击我 / /LinearLayout选择 LinearLayout 而不是模板默认的 ConstraintLayout是因为线性布局的规则足够简单方向从上到下控件依次排列。match_parent表示宽度填满父容器wrap_content表示宽高由内容决定这两个属性能解释清楚就够应对大部分基础场景了。id/tvHello中的加号是“新建资源 ID”的意思之后在 Kotlin 里就能用R.id.tvHello找到它。5.2 用Kotlin把布局加载到窗口setContentView与ViewBinding布局文件写好之后回到MainActivity.kt。setContentView(R.layout.activity_main)已经把布局加载到窗口里了。接下来要用 Kotlin 找到按钮并处理点击事件。最直接的方式是findViewByIdval button: Button findViewById(R.id.btnClick) button.setOnClickListener { val textView findViewByIdTextView(R.id.tvHello) textView.text 你点击了按钮 }这段代码能跑但每次都要写findViewById类型写错还会强转崩溃。更推荐的方式是启用ViewBinding。在app/build.gradle.kts的android {}块里加上buildFeatures { viewBinding true }然后重新同步工程改MainActivity.ktpackage com.example.ktdemo import android.os.Bundle import android.widget.Toast import androidx.appcompat.app.AppCompatActivity import com.example.ktdemo.databinding.ActivityMainBinding class MainActivity : AppCompatActivity() { private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) binding.btnClick.setOnClickListener { binding.tvHello.text 你点击了按钮 Toast.makeText(this, 按钮被点击, Toast.LENGTH_SHORT).show() } } }ViewBinding 会为每个布局文件生成一个 Binding 类activity_main.xml对应ActivityMainBinding。现在binding.tvHello、binding.btnClick直接可用类型安全、不用手写 ID 查找而且空指针的概率大幅下降。新版 Android 开发中这是主流做法建议从一开始就按这个习惯来。lateinit var是 Kotlin 里“延迟初始化”的语法适合这种在onCreate里才赋值的场景。5.3 构建APK并在模拟器或真机上运行代码写完到了最激动人心的运行环节。如果你用模拟器点击 Android Studio 右上角的Device Manager创建一个虚拟设备。选择设备时建议挑一个不带 Google Play 图标的机型镜像比如 Pixel 系列对应版本原因是 Google Play 版本的系统镜像不完全开放 root 和部分 adb 能力对调试不友好。创建完成后点击运行按钮旁边的设备下拉框选模拟器然后点绿色三角运行。如果你用真机需要先在手机设置 - 关于手机里连续点击版本号直到提示“已进入开发者模式”然后到开发者选项里打开USB 调试。用数据线连接电脑首次连接时手机会弹出确认授权框点允许。Windows 用户如果识别不到设备可能需要安装对应品牌的 USB 驱动macOS 用户通常插上就能用。连接好之后可以在终端执行adb devices验证adb devices输出中如果出现device状态说明设备已就绪。如果显示unauthorized检查手机上的授权弹窗。一切就绪后点击运行按钮Android Studio 会先执行 Gradle 构建生成 APK再安装到目标设备上并自动启动 MainActivity。5.4 Logcat和断点确认代码是否真的在跑运行成功只是第一步你还需要一套“看代码到底跑没跑”的手段。最常用的是 Logcat 日志工具。在MainActivity.kt里加上日志输出import android.util.Log private const val TAG MainActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) Log.d(TAG, onCreate called) // ... } }运行后在 Android Studio 底部打开Logcat窗口在过滤条件里输入MainActivity你应该能看到onCreate called这条日志。日志级别中Log.d是调试日志Log.e是错误日志Log.i是信息日志。养成看日志的习惯非常重要很多 app 崩溃时抛出的异常信息就在 Logcat 里只不过很多人不知道往这里看。除了 Logcat断点调试也很直观。在MainActivity.kt某一行代码左边的数字行号上单击一下出现红点然后点击Debug按钮运行。代码执行到这一行时会停下来你可以在 Debug 窗口里看到所有变量的当前值。曾经有朋友问我“按钮点击后为什么界面没反应”让他打断点跑一遍发现代码逻辑分支走错了这种问题比盯着代码干想高效得多。6. 建工程阶段的高频报错与排查经验6.1 安装卡在“Waiting for IDEA plugin”之类的画面新建工程后首次打开右下角可能会出现一条进度提示大意是正在安装插件或等待某些组件就绪。这种情况在新版 Android Studio 中通常是 Kotlin 插件和 IDE 版本在自动对齐。多数情况下稍等片刻就能过去但如果长时间卡住不动要考虑两个原因一是网络环境不稳定导致插件下载中断二是 IDE 缓存出了问题。处理办法先等待 5 到 10 分钟网络条件差的话可以换个网络环境重试。如果还是卡住不要怕重启 Android Studio重新打开工程一般会自动恢复。极少数情况下需要执行File - Invalidate Caches / Restart清空缓存。这里想强调一点新版 Android Studio 已经内置 Kotlin 支持不需要单独去装 Kotlin 插件。如果新手在插件广场看到 Kotlin 插件并手动安装反而可能装到不匹配的版本出现 IDE 打不开的情况。6.2 首次构建慢、依赖下载不动首次构建慢根本原因是 Gradle 需要下载发行包和大量依赖库。这些依赖默认来自google()和mavenCentral()仓库在国内网络环境下速度可能很慢。解决思路有两个方向。第一检查gradle-wrapper.properties确认 Gradle 版本不是过旧的版本过旧版本下载失败率更高。文件内容长这样distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.7-bin.zip zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists第二可以在根目录settings.gradle.kts中把仓库源调整为国内访问速度更快的公共仓库。前提是这些仓库确实提供了你需要的依赖版本。改完之后同步一次工程不出意外构建速度会有明显改善。这类问题的本质是“依赖从哪儿拉”不是你的代码有问题所以心态上不用慌。6.3 Failed to find target with hash string android-XX这个报错很形象编译时需要的某个 Android SDK Platform 版本你本地没装。比如报Failed to find target with hash string android-35说明你的compileSdk配的是 35但 SDK Manager 里没有安装 API 35 的 Platform。解决办法打开Settings - Languages Frameworks - Android SDK - SDK Platforms勾选对应版本安装然后重新同步工程。另一个思路是反过来把项目里build.gradle.kts的compileSdk改成你本地已安装的版本但这样可能遇到依赖库要求更高compileSdk的问题。所以正规做法还是补齐 SDK Platform。这个报错之所以高频出现是因为很多人直接 clone 别人的工程别人的compileSdk比本地高第一反应却是去改代码方向就错了。6.4 adb连不上真机真机调试连不上是另一个高频问题。现象通常是adb devices列表为空或者手机弹窗里只有“仅充电”模式。按顺序排查确认 USB 调试开关打开设置 - 开发者选项 - USB 调试。确认连接模式不是“仅充电”部分手机需要手动切换为“传输文件/MTP”模式。重新插拔数据线留意手机上的授权弹窗必须点“允许”。Windows 用户需要装驱动可以借助电脑厂家提供的手机助手工具安装统一驱动装完重启 adbadb kill-server adb start-server再执行adb devices。换一根数据线。很多数据线只能充电不能传数据这是新手最容易忽略的坑。我遇到过不少情况是前面步骤都对最后换了一根原装数据线就好了所以数据线这个点值得单独说一下。6.5 模拟器启动慢或花屏模拟器启动慢通常和电脑的虚拟化支持状态有关。新版 Android Studio 在 Windows 上依赖 Windows 虚拟机平台相关特性在 macOS 上依赖系统的 Hypervisor 框架。如果你的电脑 BIOS 里关闭了虚拟化模拟器会启动失败或者卡在开机画面。处理办法先确认电脑是否开启了虚拟化一般可以在任务管理器 - 性能 - CPU 里看到“虚拟化”状态。没有开启的话需要进 BIOS 打开 Intel VT-x 或 AMD-V 相关的开关。开启之后如果模拟器还是慢另一个常见原因是模拟器分配的运行内存太少可以在 AVD 编辑界面里把内存调到 2GB 以上同时选择 x86_64 位系统镜像这样运行速度会有质的提升。7. 工程建完之后这个系列接下来会走哪几条线7.1 建工程阶段真正锻炼的能力到这里你已经完成了第一阶段的闭环环境准备、创建工程、读懂目录结构、写了一个简单的界面、运行到了模拟器或真机上还掌握了一点 Logcat 和调试的技巧。这个过程看着不难但你真正锻炼起来的是未来一定会反复用到的能力面向报错定位问题的能力。第一次同步、第一次构建、第一次连接真机每一步都可能报错而你把这些报错一个个解决掉了这比背十遍 API 清单更有价值。我经常对初学者说报错不是坏事它是工具链在告诉你“这里的数据流断了请检查这一环”。你手里有 Logcat、有断点、有 Gradle 日志相当于有了三件排查武器。7.2 三条可选的学习路线工程跑通之后后面学习路线可以分三条线同步推进。第一条是Kotlin 语法线空安全、协程、集合操作、扩展函数。这些不是背出来的而是要在当前工程里多写多实验。比如你可以在MainActivity里写一个按钮点击时用listOf(a, b).filter { ... }过滤数据再显示到界面上语法用着用着就记住了。第二条是UI 体系线LinearLayout、ConstraintLayout、RecyclerView、Material 组件、自定义 View。第一篇文章里只用了最基本的 TextView 和 Button后续可以逐步往列表、底部导航、应用栏方向扩展。第三条是数据与网络线SharedPreferences 存键值数据、Room 存数据库、Retrofit 调接口。这是从“能跑”到“有用”的关键一步也是大多数商业 app 的日常开发内容。三条线不是先后关系而是交叉关系。每学一个新知识点都放到当前工程里加一个小功能形成“学一点、用一点、跑一遍、再看日志确认”的节奏这是我认为最不容易放弃的学习方式。7.3 我给新手的三条工程习惯建议最后分享三个我踩过坑之后形成的习惯希望能从一开始就帮你避开弯路。第一个习惯是报错先读原文不要把整段报错当噪音。构建失败时Gradle 窗口里往往有一大段日志别滚动条一拉就关掉往最后翻找以Error、FAILURE、Caused by开头的几行绝大多数问题的致命原因都在这里。很多来自搜索引擎的答案之所以对不上就是因为你贴错了报错关键行。第二个习惯是每个工程从第一天起就保持干净的代码结构。MainActivity.kt不要越写越长按钮点击事件及时抽成私有方法字符串写到资源文件布局里 ID 命名用tv_、btn_这类前缀。小程序不觉得等工程膨胀到几千行这些早期习惯能救你的命。第三个习惯是尝试自己解决问题前先记录复现步骤。模拟器跑出 bug先写下“我点了哪里、改了哪些代码、什么样的界面出现、Logcat 里有什么”带着这些信息再去找资料或问人效率会高很多。这不是繁琐这是在培养程序员最基本的排查思维。工程已经建起来了第一个界面也跑通了。下一篇文章我会带着你把这个工程往真正的 app 形态推进——加入多页面跳转、列表展示和更完整的 Kotlin 语法实践。到那时你会发现基础一旦打通后面的路其实比预想的要好走得多。 用Kotlin创建Android工程：从新建项目到真机运行
很多朋友想学 Kotlin 开发 Android app第一反应是先去啃语法、刷教程结果刷了一个月代码看得懂但一打开 Android Studio 还是不知道从哪儿下手。我见过太多这样的例子所以我一直建议第一步永远是先把一个能跑的工程建立起来让代码真正跑在模拟器或者手机上。本篇文章就是这套系列教程的第一篇目标非常明确——用 Kotlin 建立 Android 工程理解 Android Studio 生成出来的每个关键文件然后亲手写一个最简界面并运行起来。适合完全零基础的新手也适合以前写 Java、现在想切 Kotlin 的老开发。1. 为什么用Kotlin建Android工程先搞懂官方模板的分岔1.1 Kotlin成为Android首选语言对“建工程”这件事意味着什么在 2017 年 Google I/O 上Google 宣布 Kotlin 成为 Android 开发的一级语言到了 2019 年官方直接宣布Kotlin First所有官方文档、示例代码、新库优先为 Kotlin 适配。这个变化不是喊口号它实打实地改变了我们“建工程”时面对的默认选项。最直接的感受就是现在你打开 Android Studio 新建项目大多数模板的默认语言已经变成 Kotlin生成的代码也都是 Kotlin 风格。以前 Java 时代建工程时还要手动加 Kotlin 插件、配置 kotlin-stdlib 依赖现在这些步骤全部被工具链消化掉了。你只需要在向导里选一下语言Android Studio 会自动帮你把 Kotlin 插件挂到 Gradle 构建脚本里把标准库依赖写进配置。这意味着建立工程的第一个门槛已经消失剩下的就是理解“工程被建出来之后里面到底是什么”。我见过不少从 Java 转过来的朋友下意识还用 Java 的思维套 Kotlin看到class MainActivity : AppCompatActivity()时第一反应是“冒号是什么”。这里提前说一句Kotlin 用冒号表示继承替代 Java 里的extends关键字后面在解读 MainActivity 的时候还会再遇到。1.2 Empty Views Activity 与 Empty Activity 的选择XML 还是 Compose现在的 Android Studio 新建项目时最容易让人纠结的是模板选择。最常看到的两个模板是Empty Views Activity基于传统 View 体系界面写在res/layout下的 XML 文件里Kotlin 代码通过setContentView()加载布局。Empty Activity基于 Jetpack Compose界面直接用 Kotlin 代码写可组合函数没有 XML 布局文件偏向纯声明式 UI。很多教程里把这两个模板混着用读者就被绕晕了。我给新手的建议非常明确第一篇文章、第一个工程优先选 Empty Views Activity。原因有两个。第一传统 View XML 的模型直观界面是“一个布局文件 一个 Activity”你可以在 XML 里看到控件、属性也可以在 Kotlin 代码里用findViewById或 ViewBinding 找到它们这条链路符合人类理解界面的直觉。Compose 虽然写起来更简洁但它把“界面长什么样”和“界面怎么响应用户”都打散到函数里心智模型对新手来说偏抽象。第二传统 View 体系下的知识点后续学 Android 四大组件、样式主题、资源系统时会反复用到这部分基础打得牢再学 Compose 时反而更快。1.3 先建工程后学语法的学习节奏有人会问Kotlin 语法都没学怎么建工程我的回答是正因为你没学才更要先把工程跑起来。建立 Android 工程本质上是在告诉你三条信息代码文件放在哪里构建脚本写在哪里资源文件怎么组织。这些内容和 Kotlin 语法本身没多大关系但你有了一个可视化的“容器”之后再回去看val、var、函数声明、空安全就能立刻在一个真实工程里做实验。我自己带人的经验是先建工程、跑通界面、改几个文字、加一个按钮这一套流程走完新手对 Kotlin 的接受速度会明显加快。原因很简单语法是砖头工程是房子你手里得有房子才知道砖头往哪儿砌。2. 环境前置Android Studio、JDK 与 SDK 的版本协同2.1 新版Android Studio自带JDK别再手动折腾JAVA_HOME很多老教程会先让你去下载 JDK 8然后配置JAVA_HOME环境变量再安装 Android Studio。这套流程放在五年前没问题但现在反而会给自己挖坑。新版 Android Studio比如 2022 年之后的版本已经内置了 JetBrains Runtime本质就是一个 JDK新建工程时 Gradle 直接用它来跑构建你不需要、甚至不应该再去单独下载 JDK。如果你在 macOS 上单独装了 JDK 8反而可能出现“Android Gradle Plugin 需要 JDK 17但你用的是 JDK 8”这类版本冲突。正确的做法是安装 Android Studio 后打开File - Settings - Build, Execution, Deployment - Build Tools - Gradle把Gradle JDK设置为Embedded JDK或jbr-17之类的新版本。这里最常见的问题就是 Gradle JDK 被设成旧版本导致构建时报Unsupported class file major version改回内置 JDK 就能解决。2.2 compileSdk、minSdk与AGP版本之间的对应关系建立工程之前有必要先理清几个会一直陪着你开发的关键参数compileSdk、minSdk、targetSdk以及它们和 Android Gradle PluginAGP、Gradle 版本之间的关系。compileSdk编译时使用的 SDK 版本决定了你能调用哪些系统 API。新版 Android Studio 创建工程时会给一个推荐值比如 API 35。minSdk最低支持的 Android 版本低于这个版本的手机装不上你的 app。targetSdkapp 声明自己针对哪个版本做过兼容适配系统会据此决定是否开启某些行为变更。版本之间不是随便配的AGP 对 Gradle 和 JDK 都有最低要求。我用一张表总结常见的对应关系Android Studio 版本AGP 版本最低 Gradle 版本建议 JDKFlamingo 2022.28.08.0JDK 17Hedgehog 2023.18.28.2JDK 17Koala 2024.18.58.7JDK 17正常情况下Android Studio 会自动为你匹配好对应版本你不需要背这张表。但当你面向搜索引擎查错时看到的报错信息往往就藏在这些版本对应关系里。比如Minimum supported Gradle version is X.X.X翻译过来就是“你的 Gradle 太旧了升级工程里 gradle-wrapper.properties 指定的版本”。2.3 SDK Manager 里哪些组件必须装Android Studio 第一次启动后会提示你安装 Android SDK。打开Settings - Languages Frameworks - Android SDK你会看到一堆组件别慌真正必装的就这几项SDK Platform对应你compileSdk指定的版本比如 API 35。Android SDK Build-Tools编译打包过程中负责生成资源、DEX 字节码的工具集。Android SDK Platform-Tools包含 adbAndroid Debug Bridge真机调试、Logcat 输出都靠它。至于系统镜像System Image是创建模拟器时才需要下载的不等同于 SDK 必装项。首次安装时建议把 SDK Platform 和 Build-Tools 的对应版本勾选好能避免后面构建时出现各种“找不到 resource”或者“Failed to find Build Tools revision”。2.4 环境阶段的典型报错找不到SDK、构建工具缺失环境没配好时报错会很直接但新手常被吓住。我挑两个出现频率最高的说一下。一个是SDK location not found. Define a valid SDK location with an ANDROID_HOME environment variable or by setting the sdk.dir。这通常发生在你从别人那里拷贝工程、或者打开了没有 SDK 配置的工程时。解决办法在工程根目录的local.properties文件里写一行sdk.dir/你的SDK路径。另一个是Failed to find Build Tools revision 30.0.3意思是工程要求的构建工具版本本地没装。解决办法有两个打开 SDK Manager 勾选对应版本安装或者把工程里build.gradle.kts的buildToolsVersion改成本地已安装的版本。比较推荐第一个因为随意降低构建工具版本可能引入兼容问题。3. 创建工程全流程从New Project到一个能跑的App3.1 模板选择与项目信息填写环境准备好之后正式建工程。打开 Android Studio点击New Project进入模板选择界面。按前面说的左侧选Phone and Tablet右侧选Empty Views Activity点击Next。接下来是项目信息表单需要填四项。Name应用名称也是工程名称。比如KtDemo。注意不要用中文和空格因为工程名会成为目录名目录名里带空格在某些构建工具中会出奇怪问题。Package name应用包名后面单独说。Save location工程保存路径建议放在一个路径简单、没有中文的目录下。Language这里下拉框选Kotlin。Minimum SDK最低支持版本建议先选API 24。最后点击FinishAndroid Studio 会开始创建 Gradle 工程并执行首次同步。第一次同步通常会持续几分钟因为要下载 Gradle 发行版和依赖库取决于网络状况。3.2 包名Package Name为什么必须遵守反域名规则包名是 Android 应用在整个系统里的唯一身份标识。它采用反向域名规则比如com.example.ktdemo。为什么要反域名因为域名是全局唯一的把域名倒过来当命名空间能最大程度避免不同公司的应用包名冲突。包名里有几个潜规则需要注意不能以数字开头每一段不能包含连字符只能使用字母、数字和下划线。常见的反面例子是com.example.my-app连字符会让编译器直接报错。包名还决定了一件事你的 R 类和 BuildConfig 类会生成在这个包名下。所以在工程建好之后你会在app/src/main/java/com/example/ktdemo/目录下看到MainActivity.kt这个目录结构必须和包名保持一致。Android Studio 按包名帮你建好目录如果你在向导里手动修改了包名目录会自动跟着调整不需要自己建文件夹。3.3 Minimum SDK的选择逻辑很多新手对Minimum SDK没概念以为越低越好。实际上minSdk设得太低意味着你要在代码里兼容很老的系统行为比如运行时权限、存储分区这些 API 差异每一样都要写兼容逻辑设得过高又会丢掉使用老手机的潜在用户。我的建议是自己学习的话选API 24对应 Android 7.0。理由很简单从 API 24 开始多数国产 app 的最低支持线也在这个位置你在网上找到的第三方库也基本都覆盖了这个版本。而且 API 24 已支持最新的 Material Design 组件界面效果不会显得老旧。如果你做的应用只给自己用、只在最新的测试机上跑那也可以选 API 33、API 34 这类更高的版本省掉很多兼容性判断但就要接受老设备装不上的代价。这个选择的本质是“开发成本”和“覆盖范围”之间的博弈没有绝对正确只有合不合适。3.4 构建配置面板Kotlin DSL 与 Groovy DSL新版 Android Studio 创建工程时构建脚本默认用Kotlin DSL文件后缀是.kts。在向导的底部你可能看到类似“Build configuration language”的选项里面有Kotlin DSL (recommended)和Groovy DSL两个选项。两者只是写法不同能力是一样的。Kotlin DSL 的好处是脚本本身是 Kotlin 代码有类型检查IDE 补全能力强写错配置立刻能标红。Groovy DSL 是老一代方案语法更自由但靠运行时执行很多错误要等构建时才暴露。对新手来说不用纠结保持默认的 Kotlin DSL 就好。最开始的阶段你甚至不需要主动去改这些脚本只要知道“工程的构建规则写在这里”就够了。4. 读懂生成的工程骨架Gradle脚本、Manifest与第一个Kotlin文件4.1 新版工程的Gradle三件套settings、build与libs.versions.toml建好工程后第一件事不是马上写代码而是花 10 分钟把整个工程目录过一遍。先看根目录下的 Gradle 相关文件这是整个工程的构建引擎。我将关键文件的作用整理成了表格文件作用settings.gradle.kts声明仓库地址和包含哪些模块。默认只有一个:app模块仓库一般配置google()、mavenCentral()build.gradle.kts根目录声明所有模块共用的插件版本比如 AGP 版本、Kotlin 插件版本。这里不直接应用插件只是声明build.gradle.ktsapp目录app 模块的具体构建配置包括compileSdk、minSdk、依赖库列表gradle/libs.versions.toml版本目录把插件和依赖的版本号集中管理起来比如 AGP 版本、Kotlin 版本、核心库版本gradle-wrapper.properties指定 Gradle 发行版的具体版本是工程自带 Gradle 的入口新手最容易忽略的是libs.versions.toml。不知道你有没有遇到过这种场景项目里同一款依赖的版本在多处出现升级时漏改一处构建就报错。版本目录就是为了解决这个问题它把版本号统一收拢到一个文件里后面在build.gradle.kts中用libs.xxx.yyy的方式引用。看别人的开源项目时如果不懂这个机制会看不懂 build 脚本里的写法所以提前认识它很重要。4.2 AndroidManifest.xml应用的门面配置接着看app/src/main/AndroidManifest.xml。这个文件是 Android 应用的“门面登记表”系统要知道你是谁、有哪些页面、能干什么全靠它。一个最简清单长这样manifest xmlns:androidhttp://schemas.android.com/apk/res/android application android:labelKtDemo android:iconmipmap/ic_launcher android:themestyle/Theme.KtDemo activity android:name.MainActivity android:exportedtrue intent-filter action android:nameandroid.intent.action.MAIN / category android:nameandroid.intent.category.LAUNCHER / /intent-filter /activity /application /manifest这里有两个信息量最大的点。第一个是android:exportedtrue它表示这个 Activity 可以被其他应用唤起。从 Android 12 开始如果 Activity 带有LAUNCHER启动类别exported必须显式声明为 true否则安装或启动时会报错。第二个是intent-filter里的MAINLAUNCHER它告诉系统“应用图标点开后第一个打开的是 MainActivity”。4.3 MainActivity.kt 与隐藏的R类再来看MainActivity.kt这是整个工程里唯一的主力 Kotlin 文件package com.example.ktdemo import android.os.Bundle import androidx.appcompat.app.AppCompatActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) } }逐行拆解class MainActivity : AppCompatActivity()声明了一个继承自AppCompatActivity的类保证在低版本 Android 上也有兼容的主题和 Fragment 支持。override fun onCreate是生命周期入口savedInstanceState: Bundle?后面的问号表示这个参数可以为空这是 Kotlin 空安全设计的体现。R.layout.activity_main引用的是项目里res/layout/activity_main.xml这个布局文件。看到R类了吗它是在构建过程中自动生成的。你每往res目录放一个文件构建时就会在 R 类里生成对应的资源 ID。你不需要关心 R 类的源码长在哪只需要记住一个规律资源文件里有什么R 类就有什么引用。4.4 res资源目录layout、values、drawable、mipmap的职责Android 工程里所有非代码资源都放在app/src/main/res/下按目录区分类型。搞清楚每个目录的职责能帮你少踩很多资源引用错误的坑。目录存放内容常见文件示例layout/界面布局文件控制页面内容摆放activity_main.xmlvalues/字符串、颜色、尺寸、主题等资源strings.xml、colors.xml、themes.xmldrawable/位图、矢量图、形状选择器ic_launcher_background.xmlmipmap/应用图标按不同屏幕密度分文件夹ic_launcher.webp新手常犯的错误是在代码里硬编码文字比如textView.text 你好。正确做法是把文字写进values/strings.xml然后通过string/xxx引用。这样做的好处是适配多语言时只需要在values-en目录下再写一个同名字符串无需改动代码而且官方 lint 会提示硬编码问题。类似地颜色尽量用color/xxx尺寸用dimen/xxx从一开始养成资源化习惯后面做深色模式、屏幕适配会省很多事。5. 手写第一块Kotlin界面从XML布局到真机运行的闭环5.1 在activity_main.xml里搭一个简单的界面工程建好之后默认的activity_main.xml是一个空的布局。现在我们把它改成最简单的交互界面一行文字加一个按钮。打开app/src/main/res/layout/activity_main.xml用 LinearLayout 替换默认布局?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:layout_widthmatch_parent android:layout_heightmatch_parent android:orientationvertical android:gravitycenter TextView android:idid/tvHello android:layout_widthwrap_content android:layout_heightwrap_content android:textHello Kotlin android:textSize24sp / Button android:idid/btnClick android:layout_widthwrap_content android:layout_heightwrap_content android:layout_marginTop16dp android:text点击我 / /LinearLayout选择 LinearLayout 而不是模板默认的 ConstraintLayout是因为线性布局的规则足够简单方向从上到下控件依次排列。match_parent表示宽度填满父容器wrap_content表示宽高由内容决定这两个属性能解释清楚就够应对大部分基础场景了。id/tvHello中的加号是“新建资源 ID”的意思之后在 Kotlin 里就能用R.id.tvHello找到它。5.2 用Kotlin把布局加载到窗口setContentView与ViewBinding布局文件写好之后回到MainActivity.kt。setContentView(R.layout.activity_main)已经把布局加载到窗口里了。接下来要用 Kotlin 找到按钮并处理点击事件。最直接的方式是findViewByIdval button: Button findViewById(R.id.btnClick) button.setOnClickListener { val textView findViewByIdTextView(R.id.tvHello) textView.text 你点击了按钮 }这段代码能跑但每次都要写findViewById类型写错还会强转崩溃。更推荐的方式是启用ViewBinding。在app/build.gradle.kts的android {}块里加上buildFeatures { viewBinding true }然后重新同步工程改MainActivity.ktpackage com.example.ktdemo import android.os.Bundle import android.widget.Toast import androidx.appcompat.app.AppCompatActivity import com.example.ktdemo.databinding.ActivityMainBinding class MainActivity : AppCompatActivity() { private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) binding.btnClick.setOnClickListener { binding.tvHello.text 你点击了按钮 Toast.makeText(this, 按钮被点击, Toast.LENGTH_SHORT).show() } } }ViewBinding 会为每个布局文件生成一个 Binding 类activity_main.xml对应ActivityMainBinding。现在binding.tvHello、binding.btnClick直接可用类型安全、不用手写 ID 查找而且空指针的概率大幅下降。新版 Android 开发中这是主流做法建议从一开始就按这个习惯来。lateinit var是 Kotlin 里“延迟初始化”的语法适合这种在onCreate里才赋值的场景。5.3 构建APK并在模拟器或真机上运行代码写完到了最激动人心的运行环节。如果你用模拟器点击 Android Studio 右上角的Device Manager创建一个虚拟设备。选择设备时建议挑一个不带 Google Play 图标的机型镜像比如 Pixel 系列对应版本原因是 Google Play 版本的系统镜像不完全开放 root 和部分 adb 能力对调试不友好。创建完成后点击运行按钮旁边的设备下拉框选模拟器然后点绿色三角运行。如果你用真机需要先在手机设置 - 关于手机里连续点击版本号直到提示“已进入开发者模式”然后到开发者选项里打开USB 调试。用数据线连接电脑首次连接时手机会弹出确认授权框点允许。Windows 用户如果识别不到设备可能需要安装对应品牌的 USB 驱动macOS 用户通常插上就能用。连接好之后可以在终端执行adb devices验证adb devices输出中如果出现device状态说明设备已就绪。如果显示unauthorized检查手机上的授权弹窗。一切就绪后点击运行按钮Android Studio 会先执行 Gradle 构建生成 APK再安装到目标设备上并自动启动 MainActivity。5.4 Logcat和断点确认代码是否真的在跑运行成功只是第一步你还需要一套“看代码到底跑没跑”的手段。最常用的是 Logcat 日志工具。在MainActivity.kt里加上日志输出import android.util.Log private const val TAG MainActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) Log.d(TAG, onCreate called) // ... } }运行后在 Android Studio 底部打开Logcat窗口在过滤条件里输入MainActivity你应该能看到onCreate called这条日志。日志级别中Log.d是调试日志Log.e是错误日志Log.i是信息日志。养成看日志的习惯非常重要很多 app 崩溃时抛出的异常信息就在 Logcat 里只不过很多人不知道往这里看。除了 Logcat断点调试也很直观。在MainActivity.kt某一行代码左边的数字行号上单击一下出现红点然后点击Debug按钮运行。代码执行到这一行时会停下来你可以在 Debug 窗口里看到所有变量的当前值。曾经有朋友问我“按钮点击后为什么界面没反应”让他打断点跑一遍发现代码逻辑分支走错了这种问题比盯着代码干想高效得多。6. 建工程阶段的高频报错与排查经验6.1 安装卡在“Waiting for IDEA plugin”之类的画面新建工程后首次打开右下角可能会出现一条进度提示大意是正在安装插件或等待某些组件就绪。这种情况在新版 Android Studio 中通常是 Kotlin 插件和 IDE 版本在自动对齐。多数情况下稍等片刻就能过去但如果长时间卡住不动要考虑两个原因一是网络环境不稳定导致插件下载中断二是 IDE 缓存出了问题。处理办法先等待 5 到 10 分钟网络条件差的话可以换个网络环境重试。如果还是卡住不要怕重启 Android Studio重新打开工程一般会自动恢复。极少数情况下需要执行File - Invalidate Caches / Restart清空缓存。这里想强调一点新版 Android Studio 已经内置 Kotlin 支持不需要单独去装 Kotlin 插件。如果新手在插件广场看到 Kotlin 插件并手动安装反而可能装到不匹配的版本出现 IDE 打不开的情况。6.2 首次构建慢、依赖下载不动首次构建慢根本原因是 Gradle 需要下载发行包和大量依赖库。这些依赖默认来自google()和mavenCentral()仓库在国内网络环境下速度可能很慢。解决思路有两个方向。第一检查gradle-wrapper.properties确认 Gradle 版本不是过旧的版本过旧版本下载失败率更高。文件内容长这样distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists distributionUrlhttps\://services.gradle.org/distributions/gradle-8.7-bin.zip zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists第二可以在根目录settings.gradle.kts中把仓库源调整为国内访问速度更快的公共仓库。前提是这些仓库确实提供了你需要的依赖版本。改完之后同步一次工程不出意外构建速度会有明显改善。这类问题的本质是“依赖从哪儿拉”不是你的代码有问题所以心态上不用慌。6.3 Failed to find target with hash string android-XX这个报错很形象编译时需要的某个 Android SDK Platform 版本你本地没装。比如报Failed to find target with hash string android-35说明你的compileSdk配的是 35但 SDK Manager 里没有安装 API 35 的 Platform。解决办法打开Settings - Languages Frameworks - Android SDK - SDK Platforms勾选对应版本安装然后重新同步工程。另一个思路是反过来把项目里build.gradle.kts的compileSdk改成你本地已安装的版本但这样可能遇到依赖库要求更高compileSdk的问题。所以正规做法还是补齐 SDK Platform。这个报错之所以高频出现是因为很多人直接 clone 别人的工程别人的compileSdk比本地高第一反应却是去改代码方向就错了。6.4 adb连不上真机真机调试连不上是另一个高频问题。现象通常是adb devices列表为空或者手机弹窗里只有“仅充电”模式。按顺序排查确认 USB 调试开关打开设置 - 开发者选项 - USB 调试。确认连接模式不是“仅充电”部分手机需要手动切换为“传输文件/MTP”模式。重新插拔数据线留意手机上的授权弹窗必须点“允许”。Windows 用户需要装驱动可以借助电脑厂家提供的手机助手工具安装统一驱动装完重启 adbadb kill-server adb start-server再执行adb devices。换一根数据线。很多数据线只能充电不能传数据这是新手最容易忽略的坑。我遇到过不少情况是前面步骤都对最后换了一根原装数据线就好了所以数据线这个点值得单独说一下。6.5 模拟器启动慢或花屏模拟器启动慢通常和电脑的虚拟化支持状态有关。新版 Android Studio 在 Windows 上依赖 Windows 虚拟机平台相关特性在 macOS 上依赖系统的 Hypervisor 框架。如果你的电脑 BIOS 里关闭了虚拟化模拟器会启动失败或者卡在开机画面。处理办法先确认电脑是否开启了虚拟化一般可以在任务管理器 - 性能 - CPU 里看到“虚拟化”状态。没有开启的话需要进 BIOS 打开 Intel VT-x 或 AMD-V 相关的开关。开启之后如果模拟器还是慢另一个常见原因是模拟器分配的运行内存太少可以在 AVD 编辑界面里把内存调到 2GB 以上同时选择 x86_64 位系统镜像这样运行速度会有质的提升。7. 工程建完之后这个系列接下来会走哪几条线7.1 建工程阶段真正锻炼的能力到这里你已经完成了第一阶段的闭环环境准备、创建工程、读懂目录结构、写了一个简单的界面、运行到了模拟器或真机上还掌握了一点 Logcat 和调试的技巧。这个过程看着不难但你真正锻炼起来的是未来一定会反复用到的能力面向报错定位问题的能力。第一次同步、第一次构建、第一次连接真机每一步都可能报错而你把这些报错一个个解决掉了这比背十遍 API 清单更有价值。我经常对初学者说报错不是坏事它是工具链在告诉你“这里的数据流断了请检查这一环”。你手里有 Logcat、有断点、有 Gradle 日志相当于有了三件排查武器。7.2 三条可选的学习路线工程跑通之后后面学习路线可以分三条线同步推进。第一条是Kotlin 语法线空安全、协程、集合操作、扩展函数。这些不是背出来的而是要在当前工程里多写多实验。比如你可以在MainActivity里写一个按钮点击时用listOf(a, b).filter { ... }过滤数据再显示到界面上语法用着用着就记住了。第二条是UI 体系线LinearLayout、ConstraintLayout、RecyclerView、Material 组件、自定义 View。第一篇文章里只用了最基本的 TextView 和 Button后续可以逐步往列表、底部导航、应用栏方向扩展。第三条是数据与网络线SharedPreferences 存键值数据、Room 存数据库、Retrofit 调接口。这是从“能跑”到“有用”的关键一步也是大多数商业 app 的日常开发内容。三条线不是先后关系而是交叉关系。每学一个新知识点都放到当前工程里加一个小功能形成“学一点、用一点、跑一遍、再看日志确认”的节奏这是我认为最不容易放弃的学习方式。7.3 我给新手的三条工程习惯建议最后分享三个我踩过坑之后形成的习惯希望能从一开始就帮你避开弯路。第一个习惯是报错先读原文不要把整段报错当噪音。构建失败时Gradle 窗口里往往有一大段日志别滚动条一拉就关掉往最后翻找以Error、FAILURE、Caused by开头的几行绝大多数问题的致命原因都在这里。很多来自搜索引擎的答案之所以对不上就是因为你贴错了报错关键行。第二个习惯是每个工程从第一天起就保持干净的代码结构。MainActivity.kt不要越写越长按钮点击事件及时抽成私有方法字符串写到资源文件布局里 ID 命名用tv_、btn_这类前缀。小程序不觉得等工程膨胀到几千行这些早期习惯能救你的命。第三个习惯是尝试自己解决问题前先记录复现步骤。模拟器跑出 bug先写下“我点了哪里、改了哪些代码、什么样的界面出现、Logcat 里有什么”带着这些信息再去找资料或问人效率会高很多。这不是繁琐这是在培养程序员最基本的排查思维。工程已经建起来了第一个界面也跑通了。下一篇文章我会带着你把这个工程往真正的 app 形态推进——加入多页面跳转、列表展示和更完整的 Kotlin 语法实践。到那时你会发现基础一旦打通后面的路其实比预想的要好走得多。