2. 项目环境准备：Android Studio 版本要求、Gradle 配置升级、compileSdk 与 targetSdk 设置为 33+

本章聚焦适配 Android 13 通知权限前的环境基线。只有 IDE、构建工具链和目标 API 统一对齐 33+，后续章节的 runtime permission 请求、通知渠道变更和前台服务限制才能正常编译与运行。环境准备通常只需 15–20 分钟，但一旦遗漏步骤，会在编译时报出大量“资源链接失败”“清单合并冲突”或“未声明 SDK 版本”错误。

2.1 Android Studio 版本要求

Android 13 (API 33) 的 SDK 体系在 Electric Eel (2022.1.1) 稳定版中首次完整支持。更早的版本（如 Chipmunk、Dolphin）虽然可以通过手动下载 SDK 33 编译，但 Android Gradle Plugin (AGP) 内置的 lint 检查、AAPT2 解析器版本和 build-tools 可能缺少对新 API 的识别，导致误报错误或资源合并异常。

2.2 Gradle 配置升级

项目级别的 build.gradle (Project) 中需要声明 Android Gradle Plugin (AGP) 版本和 Gradle 包装器版本。Android 13 适配要求 AGP ≥ 7.4.0，Gradle ≥ 8.0。以下为推荐配置：

// 项目级 build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // AGP 版本必须 ≥ 7.4
        classpath 'com.android.tools.build:gradle:8.1.2'
        // Kotlin 插件版本可选，但建议 ≥ 1.9.0
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22'
    }
}

同时修改 gradle-wrapper.properties：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

2.3 compileSdk 与 targetSdk 设置为 33+

compileSdk 决定编译时可访问的 API；targetSdk 决定应用运行时表现的兼容性行为（例如通知权限默认关闭或自动授予）。Android 13 通知权限适配要求两者至少为 33，否则新增的 POST_NOTIFICATIONS 权限常量无法被识别，shouldShowRequestPermissionRationale() 行为也会回退至旧规则。

在模块级 build.gradle 中修改：

android {
    // 必须 ≥ 33，推荐使用 34（对应 Android 14）以同时满足后续适配
    compileSdk 34

    defaultConfig {
        // targetSdk 标记应用的兼容目标
        targetSdk 34
        // minSdk 视项目业务决定，通常 ≥ 21 即可
        minSdk 21
    }

    // 如果之前未声明，可能需要添加以下 compileOptions
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

2.4 验证与常见错误

修改完配置后必须执行一次 Clean Project 和 Rebuild，并在 Gradle Console 中观察输出。以下为最高频出现的三种错误及解决方法：

2.5 调试与稳定性备忘

• Gradle 同步卡死：尝试 File → Invalidate Caches & Restart，或删除 ~/.gradle/caches/ 下相应项目缓存。
• R8/ProGuard 混淆冲突：升级 compileSdk 后部分 keep 规则可能失效，在 proguard-rules.pro 中临时添加 -dontwarn 并逐项排查。
• 增量编译不稳定：环境切换后建议执行一次 ./gradlew clean，避免混合旧的 R 类文件。
• 持续集成 (CI) 容器：确保 Jenkins/GitHub Actions 镜像中的 SDK 已安装 platform 33+，并在 build.gradle 中通过 sdk.dir 指定正确路径。