搜过Android入门教程的人十有八九都会卡在第一个动作上创建项目。这个操作听上去就是点几下按钮可真正点开New Project之后那一堆模板、语言、SDK选项、Gradle版本瞬间能把人绕晕每个选项都像在考英语阅读理解。我写这篇就是想把这一步彻底讲透让你创建完一个Android App工程后不是只会跟着教程点鼠标而是清楚每一个选项到底决定了什么后面项目里看到的每个文件又是干嘛的。我默认你准备做的是“用Android Studio写原生App”不是跨平台框架。如果你以后想做的是运动打卡App、网约车App或者任何工具类应用这一套原生工程的创建和结构逻辑基本都是通用的值得先花半小时把它跑通。接下来我会按照从创建到运行的完整顺序来走中途会把关键选项和踩过的坑都展开讲。文章不会太“教科书”我尽量用实际开发里的大白话来说毕竟创建项目只是一个起点后面你还要天天和这些目录、配置文件打交道。1. 项目整体设计创建项目到底在创建什么1.1 一个Android项目的最小构成先说一个容易误解的地方在Android Studio里创建一个“项目”其实创建的不是“一个App”而是一个Gradle工程。这个工程里可以有一个App模块以后也可以加Library模块、测试模块只是现在我们先从单个App模块开始。一个最小Android项目通常由三块拼起来源代码、资源文件、构建配置。源代码放在app/src/main/javaKotlin或Java文件资源放在app/src/main/res布局XML、图片、字符串、颜色、主题构建配置则是根目录那一堆.gradle.kts文件。Android Studio本身不负责编译打包真正干活的是Gradle它是一个通用的自动化构建工具负责读取你的配置、下载第三方库、把源代码和资源打包成APK。你可以把Gradle理解成包工头你说要盖一栋楼它去拉砖、请工人、按图纸施工最后交出一把钥匙。理解了这层关系后面看到Android Studio里“Gradle Sync”转圈半天就不会慌了它只是在把工程依赖下载整理一遍。1.2 开发环境三件套Android Studio、JDK 和 SDK很多人下载完Android Studio就急着建项目结果一路报错。这里先把三件套说清楚Android Studio、JDK、Android SDK。Android Studio是一个IDE基于IntelliJ IDEA它自带了一个JetBrains Runtime里头包含了适合开发用的JDK所以你并不需要额外去Oracle官网装一套JDK。打开Android Studio菜单里的Settings搜索“Gradle JDK”你会看到类似jbr-21的选项这就是内置JDK。新手不用动它。Android SDK才是真正决定你App跑在哪个Android版本、能用哪些系统API的东西。它由SDK Manager管理首次打开Android Studio时会提示下载也可以在Settings里搜索“SDK Manager”进入安装Platform、Platform-Tools、Build-Tools等组件。创建项目时选了一个Minimum SDK如果本机没下载对应的PlatformStudio会提示你补装这也算最常见的开局报错之一。这三样只要版本匹配环境基本就干净了。真正麻烦的反而是后面Gradle拉依赖时网络慢、仓库访问超时那个后面会单独说。1.3 模板怎么选Empty Views Activity 还是 Compose新建项目时Android Studio会给你一堆模板Empty Activity、Basic Views Activity、Navigation Drawer Activity、Empty Views Activity等等。新版Studio默认推荐的“Empty Activity”很可能是基于Jetpack Compose的也就是纯代码写界面不用XML布局。这种模板很新但对刚起步的人并不友好因为查资料时搜到的大部分老教程用的还是XML布局那套。所以我的建议是选“Empty Views Activity”如果模板列表里没有这个就找带“Empty”且不含“Compose”字样的模板。这里不是否定Compose而是路线选择问题。传统View体系资料多、稳定性高等我把Activity生命周期、布局、列表这套基础吃透之后再切Compose会顺畅得多。第一篇文章用最稳的组合Kotlin XML布局 View系统。2. 实操在Android Studio里创建第一个项目2.1 从打开Studio到New Project全流程打开Android Studio如果之前没建过项目会看到一个欢迎页点击“New Project”。如果你已经打开了别的项目点菜单File - New - New Project效果一样。接下来会进入模板选择页。在左侧分类里找到“Phone and Tablet”右边选择“Empty Views Activity”。这一步很多新版本会显示“Empty Activity”和“Empty Views Activity”同时存在注意别选错。选好后点Next进入配置页。配置页里要填的东西比较多我逐个说。Application name是App显示在手机桌面上的名字建议首字母大写比如MyFirstApp。Package name是应用的唯一标识在Android生态里它相当于App的身份证后面上架应用商店、做微信分享、推送都跟它绑定创建之后再改包名非常痛苦。默认会生成com.example.myfirstapp这种格式学习阶段可以直接用但如果你已经知道自己将来要上架最好用自己域名的倒序比如com.yourcompany.myfirstapp。Save location就是项目保存路径我只有一个硬性建议路径里不要有中文空格也尽量避免。很多编译工具对特殊字符支持不好出现诡异问题时会让你排查到怀疑人生。2.2 关键配置速查表语言、最低版本和构建配置配置页中下半部分有几个下拉框新手最容易在这里犹豫我把我的建议整理成一张表你可以直接照着抄。配置项我的推荐理由LanguageKotlin官方主推代码简洁协程写异步很舒服Minimum SDKAPI 24对应Android 7.0覆盖率足够高不用处理太老机型Build configurationKotlin DSLStudio新版本默认配置VSCode插件和社区也照顾得更好使用AndroidX勾选新项目默认都勾不勾的话很多依赖库用不了关于Minimum SDK我再多说几句。它指的是你的App最低能在哪个Android版本上运行选得越低兼容的老设备越多但你可能要写各种版本判断和兼容代码选得越高你能放心用的新系统API越多开发和测试成本越低。API 24Android 7.0在当前的活跃设备里覆盖已经很广做学习项目完全够用。如果你的应用业务面向特别新的系统那直接选API 26或者API 29也没问题不用太纠结。点击Finish之后Android Studio就会开始创建项目第一次同步时Gradle会在后台下载一堆依赖这个过程可能持续几分钟取决于网络情况。别急着反复操作耐心等右下角进度条走完。2.3 等待Gradle同步时后台到底在做什么很多人在这一步干着急因为界面一直转圈也不知道是否卡死了。其实Gradle同步期间后台在做几件明确的事读取settings.gradle.kts和build.gradle.kts配置从远程仓库下载Android Gradle Plugin、Kotlin插件以及AndroidX组件库检查本地有没有匹配的Gradle版本没有就去下载然后生成一系列编译中间产物比如R.java、BuildConfig等。这就像你去餐厅点完菜厨房开始备菜、洗菜、切菜不是上菜慢是还没到炒菜的环节。如果等了很久还是失败那大概率是仓库地址访问不顺畅。一个常见的处理方式是在项目的settings.gradle.kts里的pluginManagement和dependencyResolutionManagement仓库地址中把google()和mavenCentral()之前或之后补充国内公共Maven镜像。比如pluginManagement { repositories { maven { url uri(https://maven.aliyun.com/repository/public) } maven { url uri(https://maven.aliyun.com/repository/google) } google() mavenCentral() gradlePluginPortal() } }改完之后重新Sync成功率会高很多。这里要注意不要只留镜像地址而删掉google()和mavenCentral()否则某些冷门依赖可能拉不到。2.4 第一次运行模拟器还是真机项目创建完成之后第一个目标就是把它跑起来。最简单的是用模拟器。点击Android Studio右上角设备选择器里的Device Manager创建一个虚拟设备先选一个硬件型号比如Pixel 6再选一个系统镜像比如API 34下载镜像完成后Finish然后点绿色运行按钮。模拟器第一次启动会慢尤其是冷启动这是正常的它本质上是在你电脑上跑一个完整的Android系统对CPU和内存都有要求。如果你是真机党操作也不复杂手机进入设置 - 关于手机连续点击“版本号”大约七次开启开发者选项然后在开发者选项里打开“USB调试”再用数据线连电脑。手机上会弹出一个授权确认框勾选始终允许并确定。部分国产ROM还会额外要求打开“USB安装”之类的开关按照提示打开就行。第一次跑起来时你会看到一个几乎空白的页面上面写着“Hello World!”这说明整个工具链已经通了。别看界面简单从下载SDK、同步Gradle到启动模拟器这一整套链路能跑通就已经跨过了入门阶段最大的那道坎。3. 项目骨架逐层拆解这些文件以后你天天见3.1 AndroidManifest.xmlApp的“户口本”运行成功之后你会发现项目结构里其实没几个文件但每个都重要。第一个要认识的就是app/src/main/AndroidManifest.xml我习惯叫它App的户口本。这个文件声明了应用包名、组件、权限和应用入口等关键信息。打开它你会看到一个application标签里面的android:label是桌面显示的名称android:icon是应用图标还有一个MainActivity的注册信息其中包含了MAIN和LAUNCHER两个意图过滤器。这意味着当用户点击桌面图标时系统会启动MainActivity。如果你以后新增了一个页面忘了在Manifest里注册运行时就会崩溃而且报错信息挺隐晦所以一定要养成新页面必注册的习惯。另外注意android:exported这个属性。新版本的Android要求四大组件必须显式声明它通常带LAUNCHER的Activity需要设为true普通页面设为false否则低版本可能装不上或者被杀毒软件拦下来。3.2 MainActivity与布局文件代码和界面是怎么连起来的MainActivity.kt是App启动后加载的第一个页面它继承自AppCompatActivity在onCreate方法里调用setContentView(R.layout.activity_main)把布局文件activity_main.xml和当前Activity绑定。这就是一个最常见的界面加载流程Activity相当于一个空房间布局文件就是房间里的家具摆设。看代码你可能会好奇R.layout.activity_main这个R是哪来的。它是由Gradle在构建时自动生成的一个资源引用类你的每一个布局文件、图片、字符串都会在R类里生成对应的静态常量。所以不要手动去改R类也不要试图在res目录之外引用资源一切交给构建系统。新版模板的MainActivity.kt里可能还会多一个enableEdgeToEdge()调用这是Android 15之后推荐的全屏“边缘到边缘”效果让内容延伸到系统状态栏后面。学习阶段可以先不深究但不建议删除它因为它和主题配置是配套的删了可能会让布局顶部和状态栏重叠。3.3 res资源目录布局、图片、字符串和主题打开res目录里面有一堆子目录layout存放界面布局文件drawable存放位图或形状图形mipmap存放应用图标values存放字符串、颜色、尺寸和主题。values目录里经常见的是strings.xml。最开始模板里会有一个app_name字符串你在桌面上看到的应用名称其实不是Activity名字而是这个字符串的值。把它改成我的第一个App重新运行桌面图标下的名字就会变这是一个很有成就感的改动。values/themes.xml定义应用主题。新建项目的默认主题是Theme.MyFirstApp它继承自一个Material风格的主题。如果以后想改状态栏颜色、去掉ActionBar、设置深色模式都会来动这个文件。布局和资源文件改起来相对独立基本是所见即所得比较适合新手边改边看效果。目录结构本身我不建议一次性背下来你先知道代码归代码资源归资源构建配置归构建配置等用多了自然就熟了。3.4 Gradle脚本三兄弟settings、build和gradle.properties再往项目根目录看会有一堆Gradle相关文件。新项目默认用的是Kotlin DSL也就是以.kts结尾的文件别被这个后缀吓到。settings.gradle.kts在最上层里面有一个include(:app)它告诉Gradle这个工程包含哪些模块。如果你以后要加一个公共库模块就在这里再加一行。模块化开发的多模块结构就是从这一行开始的。项目级build.gradle.kts一般只有插件声明不写具体业务配置。模块级app/build.gradle.kts才是重点里面包含android和dependencies两个大块。android块里能看到namespace、compileSdk、minSdk、targetSdk、versionCode和versionName。compileSdk决定编译时用哪个版本的APItargetSdk决定系统以哪个兼容策略来运行你的AppminSdk就是你之前选的那个最低版本。这三个概念以后面试和上架都会被问到现在开始记是最合适的。gradle.properties则是JVM和Gradle的行为配置比如给Gradle分配多少内存。默认配置对学习项目够用但如果你以后项目变大、模块变多经常出现编译内存溢出可以来这里调org.gradle.jvmargs.3.5 让第一个页面显示点不一样的东西只盯着“Hello World”看两分钟好奇心就会被耗尽。所以创建项目跑通之后我建议立刻动手做一个改动在屏幕上加一个按钮点击后让文字变化。在activity_main.xml里往布局里面加一个Button给TextView加一个id然后在MainActivity.kt里写这几行package com.example.myfirstapp import android.os.Bundle import android.widget.Button import android.widget.TextView import androidx.appcompat.app.AppCompatActivity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) val tvMessage: TextView findViewById(R.id.tvMessage) val btnChange: Button findViewById(R.id.btnChange) btnChange.setOnClickListener { tvMessage.text 我已经学会创建项目了 } } }这里用findViewById把布局里的控件对象“找”出来再给按钮设置点击监听。点击后修改TextView的显示文本这是一个非常典型的Android交互范式控件 - 事件 - 数据变化 - 界面刷新。学会这一小段比干看十个教程都有用。4. 实际开发中最容易踩的坑4.1 Gradle同步失败或依赖下载慢论坛里最常见的求助帖就是“创建项目后Gradle一直失败”“卡在 downloading gradle-8.x.zip”。原因大多是依赖仓库访问慢、本地代理设置残留、Gradle版本和AGP版本不匹配。我建议的排查顺序是先看左下角Build窗口里的具体报错不要只看红色大字就慌如果提示“Could not GET ...”或者“Connection timed out”优先尝试替换国内镜像如果提示“Unsupported class file major version”则是JDK版本问题去Settings里把Gradle JDK切到Studio内置版本。还有一个很多人不知道的小技巧Gradle的版本是在gradle/wrapper/gradle-wrapper.properties里锁定的它决定下载哪个Gradle发行包。除非你清楚自己在做什么不然不要手动改这个文件Studio新项目生成的版本组合通常是经过验证的。4.2 SDK、编译版本和JDK的匹配问题新手第二个高频报错是“SDK component Android SDK Platform 34 is not installed”或“AGP requires Java 17”。前者很简单去SDK Manager勾选对应Platform版本安装即可。后者也不难在Settings里搜索Gradle JDK把JDK切到17或更高版本即可。Android Gradle Plugin 8.x要求JDK 17起步Studio内置的JBR版本通常满足要求你只要别手贱去改成系统里一个很老的JDK就行。还有一个容易忽略的点compileSdk、targetSdk、minSdk三个值不要随便写compileSdk最好大于等于targetSdk而targetSdk又不能低于minSdk。这些约束在构建时会校验报错信息也写得很直白看懂一次就不会再错。4.3 模拟器卡顿和真机不识别模拟器创建好了点运行却启动不起来或者启动后像PPT一样卡这个问题和Android Studio本身关系不大主要看电脑虚拟化是否开启、内存是否充足。如果你在Windows上使用建议先检查主板的VT虚拟化是否启用如果用的是macOS确认磁盘剩余空间够大系统镜像一般要占好几个G。实在不行可以创建一个分辨率低一点的虚拟设备比如选小屏幕的旧机型运行速度会明显提升。真机不识别就更常见了。排除驱动问题后最常见的原因就是没开USB调试或者手机上弹出的“允许USB调试吗”没有点确定。有些人换了根数据线发现能充电但电脑识别不到因为那根线只支持充电不支持数据传输。换线重插或者在终端执行一下adb kill-server再adb start-server大部分问题都能解决。4.4 文件URI和网络调试的两个“隐藏雷区”这里分享两个以后一定会遇到的坑。第一个是文件URI。你在日志里很可能会看到类似content://com.tencent.wework.fileprovider/external_path/android/data/com.tencent.wework/...这样的地址这是其他App通过FileProvider分享文件时生成的内容URI属于content协议不是你熟悉的file协议。如果拿到这种URI直接当绝对路径去File解析一定会失败。正确做法是通过ContentResolver打开输入流来读取文件。这是Android 7.0以后文件共享的标准方式以后涉及图片选择器、分享功能时一定会踩到。第二个是网络调试时的“抓包失败”。Android 7.0之后系统默认不信任用户安装的CA证书所以你用抓包工具打开自己的App发现HTTPS请求是加密且无法解密的这不是工具问题。开发阶段要调试自己App的请求可以在debug包里的res/xml/network_security_config.xml配置信任用户证书或者在抓包工具里安装并信任系统证书。这个属于开发调试细节先记个概念等真到需要抓包的时候再对照处理。4.5 常见问题速查表现象大概率原因快速处理方式Gradle Sync一直失败依赖仓库访问慢或代理残留替换国内Maven镜像检查代理设置提示找不到SDK Platform本机未下载对应API版本SDK Manager里安装对应Platform提示AGP需要Java 17Gradle JDK版本过低Settings里切换内置JBR模拟器启动卡死虚拟化关闭或内存不足开启VT降低设备分辨率关闭多余程序手机不识别USB调试未开或数据线不支持数据开开发者选项USB调试换线重启adb编译时OOMGradle内存分配不足修改gradle.properties的org.gradle.jvmargs桌面应用名没变改错了app_name位置去res/values/strings.xml改新加的Activity崩溃忘记在Manifest注册检查AndroidManifest.xml5. 从模板到真实App后面应该怎么继续5.1 用“运动打卡App”当例子规划下一步项目模板跑通、基础结构看懂之后很多人会突然迷茫下一步写什么我给的建议是立刻给自己定一个小目标比如做一个运动打卡App。这个目标不需要一步到位把它拆开就能看到后续的学习路线统计每天步数需要用到传感器接口展示运动记录列表需要RecyclerView和数据适配保存记录需要Room数据库如果还要上传云端就需要Retrofit网络库。你可以先不做云端就做一个本地记录页面一个输入框记录今天跑了多少公里一个按钮保存一个列表展示历史记录。这样一个几十行代码的小功能就能把布局、Activity、数据持久化串起来。创建项目时勾选的包结构也可以按功能整理。比如在com.example.myfirstapp下面分ui、data、utils这几个包ui里再按页面拆分比把所有Kotlin文件堆在同一个目录里清晰得多。养成这种组织习惯后面项目变大时才会感激当初的自己。5.2 从“能跑”到“能上架”还差几步运行成功只是起点如果目标是发布一个App上架应用商店后面还有几条线要补注册开发者账号、准备应用图标和截图、配置签名、完善隐私政策、满足各应用市场的合规要求。其中包名和签名尤其重要因为上架后再改包名等于换了一个应用用户量会清零。成本方面常有人问“开发一个App并上架大概要多少钱”这个很难一概而论。如果自己做学习和开发主要成本是时间和一台能流畅运行模拟器的电脑如果涉及服务器、推送服务、短信验证码等那每个月会有少量服务器和接口费用。早期完全可以把技术链路先在本地跑通后面再考虑投入。5.3 养成三个小习惯能少走很多弯路创建项目这件事说起来简单但它背后是一整套工程习惯的养成。我个人的建议是第一每个学习项目都做好Git版本管理哪怕只是本地提交也能让你在改坏代码时有后悔药吃创建项目时Studio已经帮你生成了.gitignore不用白不用第二每次新建项目后第一时间把包名和应用名改成自己的风格不要一直停留在com.example免得后面纠结第三遇到构建问题先看Build窗口里的具体日志再上网搜千万不要盲目复制网上的代码。最后分享一个我自己的习惯每开一个新项目我都会先把gradle.properties里的Gradle内存调大一点然后把默认的MainActivity改个更语义化的名字再手动加一个按钮事件完整跑一遍真机和模拟器。这一套流程走下来工具链、目录结构、日志排查、调试流程都过了一遍后面再写业务功能心里就会踏实很多。创建项目就像一个房子的地基地基打稳了后面每一层楼才盖得安心。