📚 课程目录第3章颜色方案基础

3. 项目初始化与依赖安装

项目初始化是动态主题系统搭建的第一块基石。本章将引导你从零创建一个 Flutter 项目，完成 Material 3 依赖的引入，并正确配置 Android 构建环境。只有基础骨架搭稳，后续的主题、颜色 scheme、组件 shape 才能顺畅接入。

3.1 创建 Flutter 项目

使用 flutter create 命令生成标准工程结构。建议指定 --org 和 --project-name，避免包名冲突，同时关闭 Apple 和 Web 平台以缩短初始化时间（如需可后续追加）。

flutter create --org com.learn.m3 \
               --project-name dynamic_theme_m3 \
               --platforms android,ios \
               --template app \
               dynamic_theme_m3

命令执行完成后，项目目录结构如下：

dynamic_theme_m3/
├── android/
├── ios/
├── lib/
│   └── main.dart
├── test/
├── pubspec.yaml
├── analysis_options.yaml
└── README.md

关键检查点：确认 lib/main.dart 存在且 pubspec.yaml 中 environment.sdk 约束覆盖 Flutter 3.10+（Material 3 的最低 SDK 版本）。

3.2 添加 Material 3 依赖

Material 3 的核心支持已内置于 Flutter SDK 3.10+，无需额外安装第三方包。但为了获得完整的动态颜色、字体缩放和形状系统，需要在 pubspec.yaml 中显式声明 material_color_utilities 和 google_fonts（可选）。

包名	版本约束	用途	是否必须
`flutter`	`sdk: flutter`	SDK 核心库	必须
`material_color_utilities`	`^0.11.1`	动态颜色提取、HCT 色空间	强烈建议
`google_fonts`	`^6.2.1`	Material 3 推荐字体（Google Sans）	可选

编辑 pubspec.yaml，在 dependencies: 区块追加：

dependencies:
  flutter:
    sdk: flutter

  # Material 3 动态颜色工具库
  material_color_utilities: ^0.11.1

  # 可选：Material 3 字体风格
  google_fonts: ^6.2.1

保存文件后，在项目根目录执行依赖获取命令：

flutter pub get

验证：终端输出应包含 Process finished with exit code 0，且 pubspec.lock 文件中出现对应条目。

💡 版本锁定建议：material_color_utilities 的 API 在 v0.10–v0.12 间有少量 breaking change。建议先指定 ^0.11.1，待项目稳定后再升级。锁定方式：删除 pubspec.lock 后重新 flutter pub get，或直接修改 lock 文件中的 version 字段。

3.3 配置 build.gradle（Android 端）

Material 3 的部分组件依赖 Android 新版本 API（如动态取色需要 Android 12+）。修改 android/app/build.gradle 的三个关键区域：compileSdkVersion、minSdkVersion、targetSdkVersion。

配置项	推荐值	说明
`compileSdkVersion`	`34`	使用最新稳定 SDK 编译，获取最新 Material 3 API
`minSdkVersion`	`21`	Material 3 组件最低兼容 Android 5.0
`targetSdkVersion`	`34`	确保应用在 Android 14 上获得最佳主题行为

定位到 android/app/build.gradle，修改 android 块：

android {
    compileSdkVersion 34

    defaultConfig {
        applicationId "com.learn.m3.dynamic_theme_m3"
        minSdkVersion 21
        targetSdkVersion 34
        versionCode 1
        versionName "1.0.0"
    }

    // 启用 Java 8+ 编译（Material 3 内部使用）
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    // Kotlin 配置（可选，建议保持与 Flutter 标准模板一致）
    kotlinOptions {
        jvmTarget = '1.8'
    }
}

⚠️ 常见陷阱：如果使用 compileSdkPreview 或设置了 compileSdkVersion = 35（预览版），部分稳定版 Flutter 插件可能不兼容，导致编译失败。始终使用正式发布的 SDK 版本号。

同时检查 android/build.gradle（项目级）中 kotlin 和 agp 版本是否匹配：

buildscript {
    ext.kotlin_version = '1.9.22'
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.2.2"
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

3.4 完整初始化流程 SVG

下图概括了从创建项目到完成 build.gradle 配置的全部步骤与决策点：

3.5 验证配置是否正确

完成全部配置后，执行编译验证。推荐使用以下命令组合进行快速检查：

# 1. 静态分析（检查 pubspec 与语法）
flutter analyze

# 2. 构建 APK（Android 端完整编译）
flutter build apk --debug

# 3. 在模拟器/真机运行
flutter run

如果 flutter run 成功在设备上显示默认 Flutter 计数器应用，说明项目骨架已正确搭建，Material 3 依赖可用。

  ✅ 验收标准：
  flutter analyze 零错误、零警告。
flutter build apk --debug 生成 APK 文件并在 build/app/outputs/flutter-apk/ 目录下存在。
运行后应用不闪退，Logcat 中无 MissingPluginException 或 UnsatisfiedLinkError。

3.6 常见错误与修复

错误信息	原因	解决方案
`uses-sdk:minSdkVersion 21 cannot be smaller than version 23 declared in library`	某个插件要求 minSdk ≥ 23	将 `minSdkVersion` 提升至 23（或该插件要求的最高值）
`Could not resolve all artifacts for configuration ':classpath'`	AGP 版本与 Gradle 版本不匹配	更新 `android/build.gradle` 中 AGP 版本，或降级 Gradle wrapper
`Error: Cannot find module 'material_color_utilities'`	`flutter pub get` 未执行或网络失败	重新执行 `flutter pub get`，检查 `pubspec.lock` 是否生成
`warning: The 'materialColor' parameter is deprecated`	使用了旧的 Material 2 颜色 API	切换为 `colorSchemeSeed` 或 `Material3(useMaterial3: true)`，后续章节详解

3.7 构建性能优化建议

初始化阶段可提前做几项配置，加速后续开发迭代：

Gradle 缓存：在 gradle.properties 中启用 org.gradle.caching=true 和 org.gradle.parallel=true。
依赖精简：只添加真正需要的 Material 3 增强包，避免 google_fonts 预加载全部字体（使用 subset 参数）。
AndroidX 强制启用：在 gradle.properties 中加入 android.useAndroidX=true 和 android.enableJetifier=true，避免旧 support 库冲突。

# android/gradle.properties
org.gradle.jvmargs=-Xmx4G -XX:+HeapDumpOnOutOfMemoryError
org.gradle.caching=true
org.gradle.parallel=true
android.useAndroidX=true
android.enableJetifier=true

🚀 提速技巧：首次 flutter pub get 后，将 pubspec.lock 提交到版本控制。团队其他成员 clone 后直接 flutter pub get --offline，可跳过网络解析，依赖安装时间缩短 60% 以上。

3.8 小结

至此，项目初始化与 Material 3 依赖安装全部完成。你已具备：

一个配置了正确 SDK 版本的 Flutter 工程；
Material 3 动态颜色工具库 material_color_utilities；
适配 Android 14 的 build.gradle 构建环境；
一套可复用的配置检查与错误修复清单。

下一阶段将进入 Flutter 3.10+ 主题系统核心——理解 Material 3 的 ColorScheme 构造逻辑与动态取色原理，为动态主题切换奠定算法基础。