第2章 搭建开发环境与工程基础：IDE配置、SDK集成、依赖管理、项目结构初始化

按需分发（Dynamic Delivery）的工程落地依赖一套标准化的开发环境。本章覆盖从 IDE 调优、SDK 植入、依赖锁定到项目骨架初始化的完整流程。完成本章配置后，你将获得一个可编译、可调试、可扩展的基准工程。

2.1 环境总览与版本约定

下表列出课程使用的核心工具链及推荐版本。版本号锁定可避免“在我机器上能跑”的兼容性问题。

组件	推荐版本	用途
Android Studio	Hedgehog | 2023.1.1+	主 IDE（Android 平台）
Xcode	15.0+ (macOS 14+)	iOS/macOS 构建
CMake	3.28+	跨平台原生构建
Gradle	8.5+	Android 依赖管理 & 打包
Python	3.11+	脚本化工具链
Dynamic Delivery SDK	2.4.0 (最新稳定)	按需分发核心库

2.2 IDE 配置与插件安装

按需分发项目通常涉及多模块、多语言（Kotlin/Swift/C++），IDE 需要额外插件支持。

2.2.1 Android Studio 插件清单

• CMake Simple Highlighter – CMakeLists.txt 语法着色
• Gradle Task Manager – 可视化 Gradle 任务
• Json Parser – 按需分发配置文件快速校验
• ADB Wi-Fi – 无线调试按需下发流程

2.2.2 IDE 关键设置

在 Android Studio 中调整以下参数以适配大型按需分发工程：

# gradle.properties (项目级)
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m
android.useAndroidX=true
android.enableJetifier=true
kotlin.code.style=official

# local.properties (本地)
sdk.dir=/Users/<user>/Library/Android/sdk
ndk.dir=/Users/<user>/Library/Android/sdk/ndk/26.1.10909125

2.3 SDK 集成（Dynamic Delivery SDK）

SDK 以 AAR（Android）和 XCFramework（Apple）形式发布。集成步骤如下。

2.3.1 Android – Gradle 依赖

// app/build.gradle.kts
dependencies {
    implementation("com.dynamicdelivery:core:2.4.0")
    implementation("com.dynamicdelivery:module-manager:2.4.0")
    implementation("com.dynamicdelivery:network-provider:2.4.0")
    // 按需分发渠道插件（可选）
    implementation("com.dynamicdelivery:plugin-firebase:2.4.0")
}

添加仓库地址（如果 SDK 托管在私有 Maven）：

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven { url = uri("https://maven.dynamicdelivery.io/releases") }
    }
}

2.3.2 iOS – Swift Package Manager

// Package.swift 或 Xcode → File → Add Packages
// URL: https://github.com/dynamicdelivery/dd-sdk-spm.git
// 版本规则: from: "2.4.0"

// 或使用 CocoaPods Podfile
target 'YourApp' do
  pod 'DynamicDeliverySDK', '~> 2.4.0'
  pod 'DynamicDeliverySDK/ModuleManager', '~> 2.4.0'
end

2.4 依赖管理与版本锁定

按需分发的依赖图容易产生传递性冲突。课程使用 Gradle Version Catalog + Dependency Guard 双重锁定。

2.4.1 Gradle Version Catalog (libs.versions.toml)

# gradle/libs.versions.toml
[versions]
dd-core = "2.4.0"
kotlin = "1.9.22"
coroutines = "1.8.0"

[libraries]
dd-core = { group = "com.dynamicdelivery", name = "core", version.ref = "dd-core" }
dd-module-manager = { group = "com.dynamicdelivery", name = "module-manager", version.ref = "dd-core" }
kotlinx-coroutines = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }

[plugins]
android-application = { id = "com.android.application", version = "8.2.2" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

2.4.2 依赖锁定与审计

# 生成锁定文件（Gradle 8.5+）
./gradlew dependencies --write-locks

# 安装 Dependency Guard 插件后
./gradlew dependencyGuard
# 会在 app/dependencies/ 下生成 .txt 锁定基线

工具	锁定粒度	CI 阻断能力
Gradle Locking	模块级	强（版本精确匹配）
Dependency Guard	全依赖树	中（变动告警，需人工确认）
Renovate / Dependabot	仓库级	弱（仅 PR 提醒）

2.5 项目结构初始化

按需分发工程采用 多模块 + 特性分层 结构。执行以下命令创建骨架：

# 使用课程模板（推荐）
git clone https://github.com/dynamicdelivery-course/module-template.git dd-starter
cd dd-starter
./init.sh --project-name=MyDeliveryApp --package=com.example.delivery

# 或手动创建 Android 多模块工程
mkdir -p app/src/main/java/com/example/delivery
mkdir -p core/src/main/java/com/example/delivery/core
mkdir -p module-network/src/main/java/com/example/delivery/network
mkdir -p module-ui/src/main/java/com/example/delivery/ui

最终项目结构应包含以下要素：

dd-starter/
├── app/                          # 主应用壳
│   ├── build.gradle.kts
│   └── src/
├── core/                         # 按需分发核心适配层
│   ├── build.gradle.kts
│   └── src/main/java/.../
├── module-network/               # 网络模块（按需下载）
├── module-ui/                    # UI 模块（按需加载）
├── gradle/
│   └── libs.versions.toml        # 版本目录
├── build.gradle.kts              # 根构建文件
├── settings.gradle.kts           # 模块注册
├── dependency-guard/             # 依赖基线
└── scripts/
    └── verify-env.sh             # 环境验证脚本

2.6 环境验证脚本

将以下脚本置于项目根目录 scripts/verify-env.sh，用于快速检测环境就绪状态：

#!/usr/bin/env bash
# verify-env.sh — 开发环境完整性检查
set -euo pipefail

echo "=== Dynamic Delivery 环境检查 ==="

# 1. 检查 JDK
if java -version 2>&1 | grep -q "openjdk version"; then
    echo "[OK] JDK 已安装"
else
    echo "[FAIL] 需要 JDK 17+"
    exit 1
fi

# 2. 检查 Android SDK
if [ -n "$ANDROID_HOME" ] && [ -d "$ANDROID_HOME" ]; then
    echo "[OK] ANDROID_HOME = $ANDROID_HOME"
else
    echo "[FAIL] ANDROID_HOME 未设置"
    exit 1
fi

# 3. 检查 NDK
if [ -n "$ANDROID_NDK_HOME" ] && [ -d "$ANDROID_NDK_HOME" ]; then
    echo "[OK] NDK 已安装 ($ANDROID_NDK_HOME)"
else
    echo "[WARN] NDK 未设置，C++ 模块不可用"
fi

# 4. 检查 Gradle Wrapper
if [ -f "gradlew" ]; then
    echo "[OK] Gradle Wrapper 存在"
else
    echo "[FAIL] 缺少 gradlew，请执行 gradle wrapper"
    exit 1
fi

# 5. 编译验证
echo ">>> 执行编译检查..."
./gradlew :core:assembleDebug --dry-run
echo "[OK] 编译检查通过"

echo "=== 环境就绪 ==="

2.7 开发环境搭建流程总图

2.8 常见错误与排查

错误现象	根因	解决方案
Could not find com.dynamicdelivery:core:2.4.0	SDK 仓库未加入	检查 settings.gradle.kts 中 repository 配置
NDK not configured	NDK 路径缺失	在 local.properties 中设置 ndk.dir
Duplicate class com.google.protobuf...	传递性依赖冲突	运行 ./gradlew :app:dependencies 定位冲突，使用 exclude 或 force 解决
Unresolved reference: DynamicDelivery	SDK 导入失败	确认 import 语句正确，且模块已依赖 :core

2.9 性能与稳定性基线

开发环境本身的性能直接影响迭代效率。建议将以下指标纳入团队质量门禁：

• 冷启动编译：首次 ./gradlew assembleDebug ≤ 3 分钟（含依赖下载）
• 增量编译：单文件改动后重新编译 ≤ 15 秒
• IDE 索引：项目打开后索引完成 ≤ 2 分钟
• SDK 下载：按需分发 SDK 包体 ≤ 8 MB（AAR）

若冷启动编译超过 5 分钟，请检查 Gradle 守护进程内存配置，并确认是否开启了 --no-daemon 或低配 JDK。