有不少新手朋友第一次打开 Android Studio面对满屏的英文和一堆按钮第一反应不是“我要创建项目”而是“我该点什么”。我见过特别多同学卡在 New Project 这一步不是界面找不到就是创建完跑不起来。这篇就专门把“androidStudio怎么创建一个全新的项目”这件事讲透——从环境准备、模板选择到每个配置项背后到底什么意思、选错了会有什么后果再到创建完以后的第一次构建会遇到哪些坑一次讲完。适合刚接触 Android 开发的入门者也适合那些已经能写代码、但从来没认真研究过“项目是怎么被搭起来”的开发者。1. 创建项目前的环境准备先把地基打稳再动工很多人一上来就点“New Project”结果点了之后要么卡在下载依赖要么提示 SDK 找不到要么 Gradle 同步失败一整晚。其实这些都属于“环境没准备好”引发的连锁反应。真正顺手的流程是先把 Android Studio 本身的配置检查完再谈创建项目。1.1 Android Studio 版本与 JDK 的匹配关系Android Studio 现在的官方安装包通常自带了匹配好的 OpenJDK。但如果你电脑上还装了其他 JDK 版本系统环境变量里可能写的是旧版Android Studio 可能会把两个版本搞混。我建议直接检查 Android Studio 自带 JDK 的路径打开 File - Project Structure - SDK Location拉到底部看 JDK location 是否指向了内嵌的 jbr 目录不同版本路径不完全一样。如果你用的是最新版 Android Studio一般在安装目录的 jbr 文件夹下能找到如果这里指向了你以前安装的老 JDK而那个 JDK 版本过低比如没到 17那么新项目一旦启用高版本 AGP就会直接报“Unsupported Java Version”之类的错。检查 JDK 本质是为了让 Gradle 能顺利编译这一步很多人忽略但它直接决定了项目创建之后能否跑得起来。我的习惯是只要 Android Studio 能用默认配置启动就全部用自带 JDK别去改系统 JAVA_HOME。因为 Android Studio 内嵌的 JDK 是经过官方测试的和 AGP、Gradle 版本之间的兼容性有保证你强行指定外部 JDK 反而是给自己挖坑。1.2 SDK 平台与 Build-Tools 的预下载第二个容易出问题的地方是 Android SDK 版本不完整。你在创建项目时确实选了最新的 API 34但如果本机 Android SDK 目录里没有实际的 SDK Platform 34Gradle 同步时会临时去下载。这在网络差的环境下几乎是“创建必卡”。一个靠谱的做法是打开 Android Studio 的 SDK Manager左侧面板的 SDK Manager 图标或 Tools - SDK Manager在 SDK Platforms 标签页里预先勾选你要用的 API 级别比如 API 34 或 API 35和对应的 Android SDK Platform-Tools再在 SDK Tools 标签页里勾选 Build-Tools 的具体版本。理论上新版 Android Studio 会自动下载缺失组件但手动预装一次能让你创建项目的过程更干净顺畅也避免首次构建时被下载耗掉大量时间。1.3 模板选择背后的差异Empty Views Activity 与 Empty Activity创建新项目这一步Android Studio 会让你选模板Template。很多教程推荐直接选 Empty Views Activity也有人推荐 Empty Activity我把它们放在环境准备这一节后面讲是因为选错模板直接影响你后面能不能顺利跑通。Empty Views Activity基于 View 系统生成一个带 layout 和 MainActivity 的最小完整项目代码简洁不掺 Compose 相关依赖对新手理解 Android 基本结构极其友好。Empty Activity在部分新版本中被 Empty Views Activity 替代但在旧版本里仍然存在。它生成的内容和 Empty Views Activity 基本一致。Empty Compose Activity基于 Jetpack Compose 的项目会引入 Compose 插件和一系列依赖首次构建下载的东西更多代码里没有 XML layout 文件。在讲 Android Studio 创建全新项目时我强烈建议第一遍选择 Empty Views Activity之后你再自己研究 Compose 也不迟。因为 Compose 模板会在幕后引入大量 Gradle 依赖而 View 体系是最直观的入口跑起来也不会因为 Compose 版本和 Kotlin 插件版本不匹配而报错。2. 核心步骤拆解从 New Project 到 MainActivity 跑起来讲完了环境下面进入正文。Android Studio 创建新项目的完整动作大致可以分成“点击 New Project、选择模板、配置项目信息、等待 Gradle 同步、运行到模拟器或真机”五步。每步都有一些细节容易被忽略我在这里把它们串起来。2.1 点击 New Project 的入口与界面差异如果在欢迎页左侧 Welcome to Android Studio 窗格里点 New Project 即可。如果在某个已打开项目的编辑界面选 File - New - New Project... 也行。两者最终进入的向导是一样的。值得注意的一点是新版本 Android Studio以 2023.3 及之后的版本为代表把模板分类整理得特别清楚第一层是按设备类型分类的 Phone and Tablet、Wear OS、TV 等。选错分类有时会生成一个结构完全不同的工程。比如在 Wear OS 分类里创建项目生成的目录里会有一堆穿戴设备相关的代码和依赖跑在手机模拟器上反而不合适。我见过有人误创建过 Wear OS 项目然后各种调不出来最后才发现选错设备分类了。所以创建全新的 Android 项目记得直接在 Phone and Tablet 分类下找模板。2.2 填写项目信息时每个空到底该怎么填模板选好之后系统会弹出项目配置页。先重点说最基础的项目名Name、包名Package name、保存位置Save location以及语言Language和最低 SDKMinimum SDK。项目名Name是你在 Android Studio 里看到的项目标识也是最终生成的应用名默认值。一般建议用英文避免中间带空格。比如 MyFirstApp 或者 MyAppDemo 都行。如果你非要用中文也不是不行但目录路径里出现中文在后续 Gradle 缓存、第三方库兼容、NDK 编译时都有概率出幺蛾子。我用着稳妥的做法是项目名用英文但 app_name 字符串可以在 strings.xml 里单独改成中文不影响工程文件结构也不影响桌面显示名称。包名Package name是 Android 应用的唯一标识有点像 App 的身份证号。默认情况下系统会根据模块名生成类似 com.example.myfirstapp 这样的包名。这里的 com.example 是 Android Studio 自动给的占位符表情是可以通过编辑器修改的我的建议是你尽早把它改成一个有辨识度的域名反写比如 io.github.yourname.appdemo。虽然开发期间不改也没事但后面要发布到应用市场或者要集成第三方推送、支付 SDK 时包名的改动会非常麻烦。它本质上是要唯一定位你这个应用和 Java 的 package 机制是一致的既然知道迟早要改不如第一次就填对。Save location 那一栏是项目的物理保存路径。建议路径全部由英文、数字组成不要有空格。至于位置本身放到哪个目录都不是原则问题但要注意的是最好不要放到网盘同步目录或系统保护的目录里例如 C 盘根目录或者 Program Files 这类需要权限的目录。因为 Gradle 构建过程会产生大量的缓存文件和临时文件这些目录的权限约束和文件扫描逻辑会影响构建效率。语言Language下拉框里是 Kotlin 和 Java。官方现在默认推荐 Kotlin但我这么跟你说如果你完全零基础先学 Kotlin 没什么不对如果你是 Java 老手选 Java 也完全没问题。Android Studio 对 Java 的支持已经非常稳健。Kotlin 的好处是更现代、代码量少、空安全Java 的好处是传统教程多、遇到问题更容易搜到答案。选哪个都不会卡住“创建项目”这一步但需要你后续的学习路线匹配。建议是别在这上面纠结太久创建项目时选 Kotlin代码思路一样可以跑通。Minimum SDK 是一个看似简单的下拉框实际上有很多细节。它代表你的应用最低能在哪个 Android 版本上运行越低覆盖的设备越多但意味着你要处理更多的兼容性问题越高代码写起来更爽因为很多新 API 不用做版本判断但也意味着低版本设备用户用不了。我用了一个比较务实的建议开发和测试阶段可以直接把 Minimum SDK 选成和你的测试机/模拟器系统版本一致或更低。比如模拟器是 API 34那 Minimum SDK 选 21 或 23 都没问题反正在 API 34 的设备上肯定跑得起来。如果是为了上架最好根据市场占有率选定比如目前 API 21 或 API 23 就能覆盖绝大多数存量设备。不过创建项目阶段不需要过于纠结因为以后在 app/build.gradle 里随手就能改 minSdk。2.3 Gradle 同步与默认项目结构点 Finish 后Android Studio 会先把工程文件生成到本地然后立刻开始 Gradle Sync 的运行。这个过程会下载当前项目声明依赖的所有库和插件第一次可能要等一段时间和你的网络状况直接相关。在这个阶段里你会看到界面右下角有一个进度条底部的 Build 窗口会输出 Gradle 相关日志。如果你的网络状况不理想这里有两条经验可以参考优先保证首次 Sync 的时候网络通畅。可以选用本地镜像源或者直接把 Gradle 的下载链接指向国内可访问的镜像地址具体会在后面“常见问题”这一节展开。不要以为 Sync 失败就手动乱点“Invalidate Caches / Restart”先看清具体报错信息再处理。很多 Sync 失败是因为依赖下载不到而不是缓存损坏。同步成功之后会生成一套标准的 Android 工程结构。这里我把最核心的目录和文件做成了表格方便你对号入座目录或文件作用app/主应用模块所有业务代码基本都在这app/src/main/java/Kotlin 或 Java 源码目录app/src/main/res/资源目录布局、图片、字符串、颜色等都在这里app/src/main/AndroidManifest.xml应用全局配置文件声明权限、Activity、应用图标等app/build.gradle.kts 或 app/build.gradle模块级构建脚本管理依赖和模块配置settings.gradle.kts 或 settings.gradle项目级配置声明包含哪些模块build.gradle.kts 或 build.gradle项目级构建脚本通常声明插件版本Gradle Scripts/上面这些脚本文件所在的分类目录看到这些文件和目录就说明你的新项目已经成功创建。很多教程到这一步就停了但真正让我觉得“项目创建成功”的标志是App 能构建出 debug 包并在模拟器或真机上启动。所以下一步更关键。3. 第一次构建与运行把 Hello World 弄上屏幕既然项目已经创建好了接下来就是验证项目能真正跑起来。这一步会让很多新手觉得挫败——明明创建得很顺利怎么模拟器一开就出错。其实这里无非是“模拟器没启动对”“构建配置有误”“签名配置不对”几类问题。逐个来说。3.1 创建与启动虚拟设备AVD运行一个 Android 项目之前至少要有一个可用的运行目标。你可以插一台开启了开发者模式和 USB 调试的真机也可以用 Android Studio 自带的虚拟设备AVD。打开 AVD Manager 的方法右侧工具栏找 Device Manager或者在 Tools - Device Manager 里打开。如果当前还没有任何设备它会显示一个创建虚拟设备的入口。创建虚拟设备时你会遇到一个界面要你从一堆系统镜像里选择。一个常见坑很多新版的 AVD Manager 默认给的镜像可能是 x86_64 架构如果没有安装对应的 System Image会弹出下载。这里不必贪多选你自己 Android 版本匹配的稳定镜像就行。如果电脑配置一般可以优先选不带 Google Play 的镜像比如不带 Play Store 标记的因为这类镜像对硬件要求更低。另外API 级别高不代表体验好某些高 API 镜像启动更慢。创建完虚拟设备后启动它。注意模拟器的冷启动时间通常比较长几分钟甚至更久都算正常。有些人以为模拟器卡死直接关掉重开反而越来越慢。建议等一下观察模拟器窗口的状态栏是否正常显示 Android 系统和桌面。3.2 选择运行目标并点击 Run模拟器启动并进入系统之后回到 Android Studio点击工具栏上的绿色三角 Run 按钮没有 Run 按钮的可以在下拉菜单里选 Run app。在 Select Deployment Target 窗口里勾选你启动好的模拟器。如果你同时插了真机页面里也会一并列出真机设备。选中之后点 OKAndroid Studio 会开始进行 Gradle Build然后通过 ADB 把 APK 安装到目标设备上。这个阶段你会在 Build 窗口看到大量输出。成功时能看到若干任务执行完成的日志最后模拟器屏幕会显示 Hello World!。这基本就已经达成目标了。但如果你在第一次 Run 时遇到“Gradle build 失败”的情况请先不用慌。绝大多数失败不是代码问题而是仓库依赖下载不全。下面我单独把常见问题铺开讲因为到了这一步积累的经验才真正派得上用场。4. 配置文件的后续调整看懂 Gradle 再往下走创建新项目之后很多人会直接跳到写 MainActivity但理解几个关键的 Gradle 配置文件对你后面解决构建问题会有决定性帮助。安卓项目本质上是 Gradle 项目加上 Android 插件理解基本概念就是打破“看着报错不知道怎么改”的钥匙。4.1 app/build.gradle.kts 或 app/build.gradle 里的核心代码如果用新版 Android Studio 创建项目默认生成的是 Gradle Kotlin DSL 格式的构建脚本也就是 .kts 文件旧版本则普遍是 .gradle 文件。两者的书写语法有差异但表达意思完全相同。下面是 Groovy DSL.gradle版本的典型内容plugins { id com.android.application } android { namespace com.example.myfirstapp compileSdk 34 defaultConfig { applicationId com.example.myfirstapp minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 } buildTypes { release { minifyEnabled false proguardFiles getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro } } compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } dependencies { implementation androidx.appcompat:appcompat:1.7.0 implementation com.google.android.material:material:1.12.0 implementation androidx.constraintlayout:constraintlayout:2.1.4 }而对应 Kotlin DSL.kts的格式长得差不多但声明方式不一样plugins { id(com.android.application) } android { namespace com.example.myfirstapp compileSdk 34 defaultConfig { applicationId com.example.myfirstapp minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 } buildTypes { release { isMinifyEnabled false proguardFiles( getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro ) } } compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } dependencies { implementation(androidx.appcompat:appcompat:1.7.0) implementation(com.google.android.material:material:1.12.0) implementation(androidx.constraintlayout:constraintlayout:2.1.4) }我来解释几个最容易困惑的地方namespace 与 applicationId在旧版构建系统里R 类的包名和 applicationId 是在一个字段里写的后来被拆开了。namespace 设置的是源码里的包名决定了 R 类和 BuildConfig 生成的包路径applicationId 才是应用真正安装时的唯一标识。compileSdk 是编译时使用的 API 版本可以等于或高于 targetSdk。我不建议 compileSdk 低于你依赖的第三方库所要求的最低版本否则库编译不过。新项目默认生成的 compileSdk 已经匹配当前版本所以不需要乱调。targetSdk 表示应用在兼容性上“瞄准”的 Android 版本。设置越高系统会默认按更高版本的行为去约束应用例如权限策略等。它不是随便填的官方商店对这些也有要求。minSdk 是之前提到的“最低支持版本”。涉及兼容性维护成本也是需要合理规划的一项。4.2 依赖版本不一致的典型表现新项目模板自带的 dependencies 其实都是经过组合测试的。如果你创建完项目后为了追求“最新版”而手动把 appcompat、material、constraintlayout 的版本号改成网上看到的最新版本就容易翻车。我见过最典型的错误是把 appcompat 和 material 升级到不同的大版本结果编译时抛出 Theme.AppCompat 相关异常或者 MaterialComponents 主题无法正确解析。这种问题本质上是不同 AndroidX 库之间的版本兼容性受到约束而你同时改了多个库的版本导致互相冲突。如果在 AndroidX 这种成熟生态里应该优先保持整体 test 过的版本组合不要孤立地拉高某一个库。解决依赖版本冲突而不是“升级到最新”时通常的排查方式是在 Android Studio 右侧的 Gradle 面板里选中 app 模块打开 Tasks - help运行 dependencies 之类的任务导出依赖树逐条对比重复类和版本冲突点。这个过程虽然看起来繁琐但对理解依赖管理非常有帮助也是排查依赖冲突问题的通用手段。4.3 第一次创建项目后建议修改的三个小地方很多人喜欢创建完项目就一头扎进 MainActivity 开始写代码但我会先做三个小调整这三个小调整能省去后面的大量麻烦第一把 kotlinOptions 或 compileOptions 的编译级别确认一下。不同模板生成的 Java 兼容性设置可能不同如果后续要引入某个库报错“Unsupported class file major version”多半要来这里调整。你知道它在哪里排查时会快很多。第二在主工程根目录的 gradle.properties 文件里我习惯加一行org.gradle.jvmargs-Xmx2048m -Dfile.encodingUTF-8这行的作用是给 Gradle 分配更大的内存并强制文件编码为 UTF-8。如果你的项目以后会变大这一行配置能避免很多因为内存不足或编码混乱导致的怪问题。默认模板其实也有类似的配置但数值可能不够高改成 2048m 能更舒服。第三把 .gitignore 文件看一下。Android Studio 默认生成的工程里有 .gitignore分别位于根目录和 app 目录。我见过有人初始化仓库时不保留这两个文件结果把 build 目录、.gradle 目录一起提交到版本库里仓库体积爆炸。新项目第一件事就是确认这两个忽略文件存在并且在正常忽略 local.properties这个文件记录的是本机 SDK 路径根本不该入库。5. 创建过程中的常见问题与排查技巧实录这一节我专门整理创建项目时最高频的几类问题都是一些我踩过、或者看着别人反复踩的坑。每一条都会给出排查思路而不是只给一句“重启试试”。5.1 创建后 Gradle 一直转圈或下载极慢常见原因很多但最终表现都一样Gradle Sync 进度条卡在“Downloading dependencies”之类的位置不动弹。这通常是网络访问 Google 仓库如 google()、mavenCentral()受限导致的这种现象在某些网络环境下确实存在。解决方案是使用国内可稳定访问的仓库镜像一般是在 settings.gradle.kts 或 settings.gradle 里把依赖仓库地址替换为镜像。我以最常用的阿里云仓库为例把 settings.gradle 的仓库配置改成pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/central } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } } dependencyResolutionManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/central } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }不过你要特别注意一点不要直接复制后无脑替换。因为新版 Android Studio 默认生成的 settings 里可能有 include app 这类模块声明你只需要把仓库仓库部分额外加上镜像源即可。另外改了镜像之后如果已经有部分依赖在本地缓存里它可能会优先用缓存不会有什么问题如果构建日志里显示“Could not find”某依赖先去检查镜像地址是否拼写正确以及它是否存在你所需的版本。5.2 提示找不到 SDK 或 SDK license 未接受在新机器上创建新项目时会看到类似“SDK location not found”或者“You have not accepted the license agreements of the following SDK components”的提示。前者说明 local.properties 里的 sdk.dir 指向错误或者该文件缺失你需要在 Android Studio 的 SDK Manager 中确认 SDK 实际路径然后在 Project Structure 里重新指定。后者常见于通过命令行直接构建的场景某些新手被教程带着在终端里执行 gradle assembleDebug 时最容易遇到。命令行构建不会自动接受 SDK 的 license所以需要用 sdkmanager 工具手动接受。一般在 Android Studio 安装目录的 cmdline-tools 里运行 sdkmanager --licenses输入若干次 y 即可。要注意的是如果 Android Studio 本身可以正常构建只是命令行不行那基本就是环境变量和 sdkmanager 路径的问题不属于创建项目本身的 bug。5.3 首次运行模拟器时间太久或启动异常模拟器冷启动慢很常见但如果一直黑屏或者卡在“Waiting for target device to come online”这时应该检查两点一是系统镜像架构和宿主 CPU 是否匹配二是模拟器加速是否打开。在 Windows 机器上如果 BIOS 没有开启硬件虚拟化功能模拟器的启动速度会惨不忍睹甚至根本无法完成启动macOS 的 Intel 和 Apple Silicon 芯片也有对应的镜像区分选了错误架构的镜像性能会极差。如果要更稳妥我建议直接使用真机调试。只要在手机开发者选项里开启 USB 调试并在 Android Studio 里选择设备就能替代模拟器。对配置不高的电脑来说真机调试验证新项目会比模拟器快得多体验也更好。5.4 新项目改 MainActivity 后无法解析符号还有一种特别常见的情况是项目创建后你在 MainActivity 里写了业务代码但编辑器一直红标提示 Unresolved reference 或者 Cannot resolve symbol。此时不用怀疑是自己的代码写错了大概率是两个原因一是 IDE 还没完成 Gradle Sync在编辑器右上角会有一个“Sync Now”的链接或者进度条等它结束再写代码二是你直接删除了模板里某个依赖而后面的代码还在引用它如 Intents、RecyclerView。出现这种情况时先执行一次 File - Sync Project with Gradle Files而不是去改代码。6. 收尾分享理解项目本质比点击按钮更重要我见过不少人成功跑起第一个 Android 项目但没过一周就放弃因为他们把“创建项目”理解成了“点击 Next 和 Finish”。Android Studio 确实把创建新项目简化到不能再简化了但工程结构里隐藏的信息量并不少。新建项目看起来很简单真正难得的是你在脑子里把“项目结构、构建脚本、SDK 版本、依赖来源”这四件事连接起来。以后你再创建一个新项目时我希望你注意的就不只是“怎么点”而是下面这几件事项目根目录的 settings 文件里声明了哪些仓库、app 模块的 build 文件里设置了哪些 SDK 版本、MainActivity 注册在哪个 Manifest 文件里。如果这些都能在你创建完项目后自行找到对应位置那这个“全新项目”就真的属于你了。最后分享一个个人习惯每次创建完项目我会习惯性把模板里的默认注释代码删掉重写一个极简的 setContentView 和 Toast 输出。不是嫌模板代码碍眼而是给自己一个信号——这个项目从第一行代码就是我控制的出问题了我也知道去哪里排查。如果你也能养成类似对照结构、重写清洁代码的习惯后面学习任何 Android 技术都会顺很多。