1.2 实验：创建第一个 Android 项目

1.1 先确定本次实验的项目信息

这份文档可复用于后续不同实验。开始前，请先确定本次实验的项目参数，后续步骤统一按这张表填写。

参数名	说明	示例
`APP_NAME`	项目名（应用名）	`FirstApp`
`PACKAGE_NAME`	包名	`cn.edu.sziit.android.firstapp`
`PROJECT_DIR`	项目保存的父目录（不含项目名）	`D:\AndroidProjects\`
`MIN_SDK`	最低支持版本	`API 24`

参数含义：

APP_NAME（应用名）：会显示在 Android Studio 的项目列表中，也常用于生成默认目录名。
PACKAGE_NAME（包名）：应用在 Android 系统中的唯一标识。发布、安装、组件注册都依赖它。
PROJECT_DIR（项目目录）：你存放所有实验工程的总目录。每次新建实验时，Android Studio 会在这个目录下再创建一个 APP_NAME 子目录。
MIN_SDK（最低支持版本）：你的应用能运行的最低 Android 版本。值越低，可运行设备越多；值越高，可使用的新 API 越多。

命名建议：

APP_NAME 使用英文，推荐大驼峰，不要空格和中文。
PACKAGE_NAME 建议使用反向域名格式，全小写。
PROJECT_DIR 路径不要包含中文或空格。

1.2 打开新建项目向导

创建新项目通常有几种入口，取决于你当前是否已经打开了某个工程：

如果 Android Studio 还没有打开任何项目，会先进入欢迎页，可以直接点击 New Project。
如果 Android Studio 还没有打开任何项目，但欢迎页上列出了之前的项目，则需要点击 Create New Project 进入新建项目向导。
如果 Android Studio 当前已经打开了其他项目，则不会再显示欢迎页，需要通过菜单 File → New → New Project… 进入新建项目向导。

下面两张图分别对应这两种进入方式：

无论从哪一种入口进入，最终都会打开同一个“新建项目向导”，后续操作完全一致。

1.3 选择项目模板

左侧选择 Phone and Tablet，右侧模板中选择 No Activity：

选好后点击 Next。

1.4 配置项目基本信息

在 Configure Your Project 页面，填写以下内容：

各字段说明：

Name：填写你在 1.1 中确定的 APP_NAME
Package name：填写你在 1.1 中确定的 PACKAGE_NAME
Save location：填写你在 1.1 中确定的 PROJECT_DIR，项目目录建议为 <PROJECT_DIR><APP_NAME>
Language：选择 Kotlin
Minimum SDK：按本次实验要求填写 MIN_SDK（若无特别要求可用 API 24）

⚠️ 路径中不要使用中文或空格。

填写完成后，点击 Finish。

什么是 Gradle Sync？
Gradle 是 Android 项目的构建工具。每次打开项目或修改配置后，Android Studio 会执行一次 Gradle Sync（同步）：读取配置文件、下载构建工具和依赖库，让 IDE 理解整个项目结构。Sync 完成后，代码才能正常编译运行。

项目刚创建完成后，Android Studio 会自动发起第一次 Gradle Sync。但此时我们还没有配置国内镜像，直接等待往往会非常慢。

因此，先把这次自动 Sync 停掉，等镜像配置完成后再手动同步。

2.1 识别自动 Sync

你会在底部状态栏或 Build 面板看到类似提示：

2.2 停止当前 Sync

可以使用以下方式：

打开底部 Build 面板，点击停止按钮

取消当前 Sync 不会损坏项目，只是停止这一次下载流程。

取消后，先继续完成接下来的镜像配置，再手动执行 Sync。

默认情况下，Gradle 相关文件从境外服务器下载，在国内速度极慢甚至超时。需要修改以下两个文件，将下载地址替换为国内镜像：

文件	所在目录	作用
`gradle-wrapper.properties`	`gradle/wrapper/`	指定 Gradle 本体的下载地址
`settings.gradle.kts`	项目根目录	配置依赖库的仓库地址

3.1 修改 Gradle 本体下载地址

在左侧 Project 面板中打开 gradle/wrapper/gradle-wrapper.properties。
为了让文档适配不同 Gradle 版本，建议删除 distributionSha256Sum，再修改 distributionUrl：

#Fri Mar 20 20:02:31 CST 2026
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionSha256Sum=b266d5ff6b90eada6dc3b20cb090e3731302e553a27c5d3e4df1f0d76beaff06
distributionUrl=https\://services.gradle.org/distributions/gradle-9.3.1-bin.zip
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.3.1-all.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

上面的修改，将下载的组件从 gradle-9.3.1-bin.zip 修改成了 gradle-9.3.1-all.zip。这是因为Android Studio除了默认下载bin文件外，还会额外下载gradle相关的源码和文档，且会尝试从 services.gradle.org 域名进行下载，导致下载过程依旧很耗时。而 gradle-9.3.1-all.zip 组件则包含了所有必要的文件，从而阻断了Android Studio这一行为。

将 distributionSha256Sum 属性删除了，因为它是针对原下载地址的校验值，修改下载地址后这个值就不适用了。如果保留这个属性，Gradle 会因为校验失败而无法下载新的 Gradle 包。

说明：

删除后不会阻止项目同步，更适合课堂里不同版本模板的统一操作。
如果你在企业项目中有安全校验要求，可以保留该行，并改为与目标 Gradle 包匹配的 SHA-256 值。

3.2 修改仓库镜像地址

打开项目根目录下的 settings.gradle.kts，只修改 repositories 相关部分：

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

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        maven { url = uri("https://maven.aliyun.com/repository/central") }
        google()
        mavenCentral()
    }
}

说明：

在 settings.gradle.kts 中： pluginManagement { repositories { ... } } 这一段负责“构建插件从哪里下载”。
在 app/build.gradle.kts 中： plugins { id("com.android.application") ... } 这一段就是“正在使用哪些构建插件”。
在 settings.gradle.kts 中： dependencyResolutionManagement { repositories { ... } } 这一段负责“项目依赖从哪里下载”。
在 app/build.gradle.kts 中： dependencies { implementation(...) } 这一段就是“项目实际使用了哪些依赖库”。

镜像配置完成后，手动执行 Sync。

4.1 触发方式

以下任一方式都可以：

顶部黄色提示条中的 Sync Now

顶部工具栏中的 大象图标

4.2 判断是否成功

底部 Build 面板出现类似内容：

成功标志：

底部出现 BUILD SUCCESSFUL
顶部不再转圈

首次Sync项目，可能会消耗比较长的时间，因为需要下载相关的构建工具和依赖库。后续Sync会快很多。

默认生成的项目主题继承自 DarkActionBar，会在屏幕顶部显示一条系统 ActionBar。本课程的布局均自行设计顶部导航，因此需要将主题改为 NoActionBar，隐藏系统自带的 ActionBar。

Android 将日间与夜间主题分别存放在两个文件中，两个都需要修改。

日间主题：打开 app/src/main/res/values/themes.xml，将父主题由 DarkActionBar 改为 NoActionBar：

<resources xmlns:tools="http://schemas.android.com/tools">
    <!-- 删除原有代码 -->
    <style name="Base.Theme.LifecycleDemo" parent="Theme.MaterialComponents.DayNight.DarkActionBar">

    <!-- 替换成以下代码 -->
    <style name="Base.Theme.LifecycleDemo" parent="Theme.MaterialComponents.DayNight.NoActionBar">
        ...
    </style>
</resources>

夜间主题：打开 app/src/main/res/values-night/themes.xml（注意：夜间主题对应的是values-night目录下的theme.xml文件），同样修改父主题：

<resources xmlns:tools="http://schemas.android.com/tools">
    <!-- 删除原有代码 -->
    <style name="Base.Theme.LifecycleDemo" parent="Theme.MaterialComponents.DayNight.DarkActionBar">

    <!-- 替换成以下代码 -->
    <style name="Base.Theme.LifecycleDemo" parent="Theme.MaterialComponents.DayNight.NoActionBar">
        ...
    </style>
</resources>

修改完成后，运行应用时屏幕顶部将不再显示系统 ActionBar，界面外观完全由布局文件控制。

为了使后续代码中操作UI控件更方便，可以在项目中启用 ViewBinding 特性。

在 app/build.gradle.kts 的 android {} 块中加入：

buildFeatures {
    viewBinding = true
}

添加后再次执行 Sync。

启用后，像 activity_main.xml 这样的布局文件会自动生成一个对应的绑定类，例如 ActivityMainBinding，后续可以直接通过它访问页面控件。

由于我们选的是 No Activity 模板，所以项目初始状态下没有界面。现在需要手动创建第一个界面。

7.1 创建方式

在左侧 Project 面板中，展开app → src → main → java → 你的包名，并鼠标点击选中包名文件夹。接着，使用鼠标右键点击包名，选择New → Activity → Empty Views Activity：

⚠️ 这里依然要选 Empty Views Activity，不要选基于 Compose 的模板。

7.2 配置 Activity 信息

在弹出的窗口中填写：

勾选Launcher Activity选项，表示将此Activity作为应用的启动页。一个APP中，至少应该有一个启动页

点击 Finish。

创建后，Android Studio 会自动生成：

MainActivity.kt
res/layout/activity_main.xml
AndroidManifest.xml 中的启动注册信息

7.3 在 AndroidManifest.xml 中确认注册信息

打开 app/src/main/AndroidManifest.xml，确认文件中已出现如下内容：

<manifest ...>
    <application ...>
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

需要确认两件事：

<activity android:name=".MainActivity"> 存在，说明 MainActivity 已被注册到系统中。
<intent-filter> 块存在，且包含 MAIN + LAUNCHER 两个标签，说明这个 Activity 是应用的启动入口。

什么是 intent-filter（意图过滤器）？

intent-filter 的作用是告诉系统：“这个组件能响应哪些类型的请求”。

Android 没有统一的”程序入口”概念，应用启动是通过系统发送一个”意图”（Intent）来实现的：系统在用户点击应用图标时，广播一个意图：action = MAIN，category = LAUNCHER。所有注册了能匹配这个意图的 Activity，就会被当作启动首页显示出来。

因此，如果你创建 Activity 时忘记勾选 Launcher Activity，AndroidManifest.xml 中就不会有这个 intent-filter，应用点击图标也不会打开任何界面。

7.4 使用 ViewBinding 设置页面布局

启用 ViewBinding 后，Activity需要改为通过绑定类加载布局，替换方式如下：

import ...
import cn.edu.sziit.android.firstapp.databinding.ActivityMainBinding

class MainActivity : AppCompatActivity() {

    private lateinit var binding: ActivityMainBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 删除原有的 setContent 函数的调用
        setContentView(R.layout.activity_main)

        // 替换成以下代码
        binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)

        // 后续访问布局中的控件时，直接通过 binding.控件id 即可，无需再调用 findViewById()。
        ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
        ViewCompat.setOnApplyWindowInsetsListener(binding.root) { v, insets ->
            val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
            v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
            insets
        }


    }
}

ActivityMainBinding 是由 activity_main.xml 自动生成的绑定类，binding.root 就代表这个布局的根视图（即布局 XML 文件最外层的那个容器，整个页面的所有控件都嵌套在它里面）。

上方代码块中还有一处改动值得注意：ViewCompat.setOnApplyWindowInsetsListener(...) 的第一个参数从 findViewById(R.id.main) 改成了 binding.root。这行代码的作用是让布局自动适配手机状态栏、导航栏等系统区域，避免内容被遮挡；它需要一个根视图作为参数。因为我们已经通过 binding.root 拿到了根视图，就不需要再用 findViewById 去查找一次——两者效果完全相同，统一用 binding.root 即可。

8.1 先确认模拟器已启动

如果你还没有模拟器，可以参考《1.1 搭建Android开发环境》中的”创建模拟器并启动验证”步骤。

模拟器启动成功后，应能看到 Android 锁屏或桌面界面。

8.2 在工具栏中选择设备

顶部工具栏会显示当前运行目标：

点击设备下拉框，选择你已经启动的模拟器。

8.3 点击运行

点击绿色 ▶ Run ‘app’ 按钮，或按快捷键Shift + F10。

点击后，Anroid Studio会先执行应用的构建流程，你可以在Build面板中看到构建成功的日志：

构建完成后，Android Studio 会执行应用安装与启动的流程，在 Run 面板会显示类似日志：

8.4 看到应用界面打开即表示成功

如果一切正常，模拟器里会自动打开你的 App，并显示默认页面。

这里显示一个空白页面是符合预期的，因为我们还没有往页面中添加任何UI控件

这表示：

项目创建成功
代码已编译成功
APK 已成功安装到模拟器
第一个 Activity 已正常启动

在你已经成功运行过一次项目之后，再回头看项目结构会更容易理解。

9.1 认识 Android Studio 主界面

Android Studio 主界面主要由以下区域组成：

区域	说明
左侧 Project 面板	显示项目文件结构
中央编辑器	编辑 Kotlin 代码和 XML 布局
顶部工具栏	运行按钮、设备选择、Sync 按钮
底部 Build / Run / Logcat	查看构建与运行日志，也可通过页面左下方的菜单栏切换不同的面板
右侧工具面板	可以通过最右侧的菜单栏打开不同的工具面板

如果某个面板不见了，可以通过菜单 View → Tool Windows 再次打开。

9.2 Project 视图下的结构

在左侧面板顶部下拉菜单中选择 Project 视图，可以看到项目真实的文件系统结构：

MyFirstApp/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/cn/edu/sziit/android/myfirstapp/
│   │   │   │   └── MainActivity.kt       ← 界面逻辑代码
│   │   │   ├── res/
│   │   │   │   ├── drawable/             ← 图片/图形资源
│   │   │   │   ├── layout/               ← 界面布局 XML 文件
│   │   │   │   │   └── activity_main.xml
│   │   │   │   ├── mipmap-*/             ← 各分辨率应用图标
│   │   │   │   └── values/               ← 颜色、字符串、主题定义
│   │   │   │       ├── colors.xml
│   │   │   │       ├── strings.xml
│   │   │   │       └── themes.xml
│   │   │   └── AndroidManifest.xml       ← 声明应用组件和权限
│   │   ├── androidTest/                  ← 仪器化测试
│   │   └── test/                         ← 单元测试
│   └── build.gradle.kts                  ← 模块配置和依赖
├── gradle/
│   ├── libs.versions.toml                ← 统一管理依赖版本
│   └── wrapper/
│       └── gradle-wrapper.properties     ← Gradle 版本和下载地址
├── build.gradle.kts                      ← 项目级构建配置
├── gradle.properties                     ← Gradle 全局开关
└── settings.gradle.kts                   ← 仓库地址与模块声明

10.1 Gradle Sync 一直转圈

先确认你已经完成第 3 步中的镜像配置，然后点击底部停止按钮取消当前 Sync，再重新点击 Sync Now。

10.2 报错 `Could not resolve ...`

通常是仓库地址写错、镜像未配置完整，或 libs.versions.toml 中版本号有误。优先检查：

settings.gradle.kts 中的阿里云仓库地址
gradle-wrapper.properties 中的腾讯云地址
libs.versions.toml 是否与文档一致

10.3 Run 按钮是灰色

通常是因为 Sync 尚未完成，或者上一次 Sync 失败。先等到底部出现 BUILD SUCCESSFUL，再运行。

10.4 模拟器运行后黑屏

先等待 2-3 分钟。如果仍黑屏，可以在 Device Manager 中对模拟器执行 Cold Boot 或 Wipe Data 后重新启动。

10.5 `ActivityMainBinding` 报红

如果你启用了 ViewBinding，但 ActivityMainBinding 仍报红，说明还没有执行 Sync。再次点击 Sync Now 即可。