这次我们来看一个 Kotlin 生态里正在发生的重要变化JetBrains 宣布其构建工具实验项目 Amper 停止开发并正式将 Kotlin Toolchain 确立为 Kotlin 多平台KMP项目的官方构建工具链。对于正在或计划使用 Kotlin 进行跨平台开发的团队来说这是一个必须关注的技术转向。简单来说Amper 曾是 JetBrains 探索的一个现代化、声明式的项目配置工具旨在简化 Kotlin 项目的构建配置。然而经过一段时间的实验JetBrains 决定将资源集中到 Kotlin Toolchain 上使其成为 KMP 的“一等公民”。这意味着未来 Kotlin 跨平台项目的构建、依赖管理和原生编译等核心能力都将围绕 Kotlin Toolchain 来构建和优化。本文的核心是帮你理清这个变化意味着什么以及你接下来该怎么做。我们会快速对比 Amper 和 Kotlin Toolchain 的核心差异然后重点讲解如何从零开始或者从现有项目迁移到 Kotlin Toolchain。内容会涵盖环境准备、项目配置、常见任务如编译、测试、发布的操作以及如何利用 Kotlin Toolchain 的特性来提升你的 KMP 开发体验。无论你是 KMP 的新手还是正在评估构建工具这篇文章都能提供直接的、可落地的指导。1. 核心能力速览Kotlin Toolchain vs. Amper在深入细节之前我们先通过一个表格快速了解 Kotlin Toolchain 的核心定位和它与 Amper 的关键区别。这能帮你快速判断迁移的必要性和价值。能力项Kotlin Toolchain (当前方向)Amper (已停止开发)官方定位Kotlin 多平台KMP的官方构建工具链和依赖管理解决方案。JetBrains 的实验性项目配置工具。核心目标提供统一、强大、可扩展的构建体验深度集成 KMP 特性支持从简单库到复杂应用的各类项目。探索更简洁、声明式的项目配置方式减少样板代码。配置语言基于 Kotlin DSLbuild.gradle.kts功能强大且灵活。基于 YAML追求极简。生态集成与 Gradle 生态无缝集成能利用海量 Gradle 插件和社区资源。生态相对封闭插件和社区支持有限。成熟度与支持获得 JetBrains 官方全力支持是 KMP 未来的基石。已停止新功能开发仅进行维护性更新不推荐用于新项目。学习与迁移成本需要学习 Gradle Kotlin DSL但知识可复用于整个 JVM/Android 生态长期收益高。配置简单易上手但技能无法迁移且项目未来存在风险。适合场景所有新的 Kotlin 多平台项目计划长期维护和扩展的现有项目。仅适用于进行技术原型验证或短期实验不适用于生产。结论先行对于任何严肃的 Kotlin 多平台开发现在都应该直接选择 Kotlin Toolchain。它不仅功能更完整而且代表了官方未来的技术方向能确保项目的长期可维护性和生态兼容性。2. 适用场景与使用边界Kotlin Toolchain 主要服务于使用 Kotlin 进行跨平台开发的场景。理解它的边界能帮助你更有效地利用它。它非常适合开发共享业务逻辑的 KMP 库将核心逻辑写在commonMain中供 Android、iOS、JVM、JS 等多个平台使用。构建完整的跨平台移动应用使用 Compose Multiplatform 开发 UI一套代码同时生成 Android APK 和 iOS IPA。开发桌面或 Web 全栈应用利用 KMP 在 JVM后端、JS前端甚至原生桌面平台共享代码。需要复杂构建流程的项目例如自定义编译任务、集成代码质量检查Detekt、生成文档Dokka、管理多版本发布等。它可能不是最佳选择或需要额外考量纯单平台项目如果你只开发 Android 或纯 JVM 后端使用标准的 Android Gradle Plugin 或 Gradle 即可无需引入 KMP 和 Toolchain 的额外概念。对构建性能极其敏感的超小型项目KMP 和 Gradle 会引入一定的构建开销。对于极其简单的单文件项目可能显得“杀鸡用牛刀”。团队完全不具备 Gradle/Kotlin DSL 知识虽然 Kotlin Toolchain 是方向但初期学习曲线确实比 Amper 的 YAML 要陡峭。这需要团队投入学习成本。合规与协作边界依赖管理需要确保所有第三方依赖的许可证符合项目要求。原生编译为 iOS 等平台编译需要相应的 SDK 和工具链并遵守对应平台的开发者协议。构建环境一致性建议使用 Gradle Wrapper 和版本锁定的方式确保团队每个成员以及 CI/CD 环境的构建结果一致。3. 环境准备与前置条件在开始创建或迁移项目之前请确保你的开发环境满足以下要求。一个稳定的环境是后续所有操作的基础。1. 操作系统开发macOS, Windows 10/11, 或 Linux 发行版均可。注意如果需要为iOS平台编译则必须在macOS系统上进行。2. Java 开发工具包 (JDK)版本推荐使用JDK 17或JDK 21LTS 版本。Kotlin 编译器与新版 JDK 兼容性更好。检查方式在终端运行java -version。安装可从 Adoptium 或 Oracle 官网下载。3. Kotlin 与 Gradle你不需要单独安装 Kotlin 编译器或 Gradle。现代 Kotlin 项目都推荐使用Gradle Wrapper它会自动下载项目中指定的 Gradle 版本而 Gradle 又会自带 Kotlin 编译器。重点在于 IDE 能正确识别 Wrapper。4. 集成开发环境 (IDE)首选 IntelliJ IDEA社区版或旗舰版均可。它对 Kotlin、KMP 和 Gradle Kotlin DSL 的支持最为完善。Android Studio从 Flamingo 版本开始已内置对 KMP 的良好支持适合开发包含 Android 目标的跨平台应用。确保插件最新在 IDE 中检查并更新 Kotlin 插件到最新版本。5. 平台特定环境按需Android安装 Android SDK并配置ANDROID_HOME环境变量。iOS安装 Xcode 及命令行工具。确保 Xcode 的路径被正确配置。其他原生平台根据目标平台如 macOS、Linux、Windows、watchOS 等安装相应的编译工具链。环境验证清单在终端依次执行以下命令确保基础环境就绪# 检查 Java java -version # 应显示 JDK 17 或 21 # 检查 Git用于拉取模板 git --version4. 创建基于 Kotlin Toolchain 的新 KMP 项目对于新项目最推荐的方式是使用 JetBrains 官方提供的项目模板这能确保你获得最新、最标准的 Kotlin Toolchain 配置。方法一使用 IntelliJ IDEA 新建项目最直观打开 IntelliJ IDEA选择New Project。在左侧列表中选择Kotlin Multiplatform。在右侧的Project Template中你可以选择Application跨平台应用模板包含 Compose Multiplatform。Library跨平台库模板。Full-Stack Web Application包含 Ktor 后端和 React 前端的全栈模板。选择模板后配置项目名称、位置、以及你想要启用的目标平台如 Android、iOS、JVM、JS。点击Create。IDEA 会自动生成项目结构并下载所有必要的依赖。方法二使用官方 GitHub 模板更灵活JetBrains 在 GitHub 上维护了多个模板仓库你可以直接克隆并以此为基础开发。# 例如克隆 Compose Multiplatform 应用模板 git clone https://github.com/JetBrains/compose-multiplatform-template.git my-kmp-app cd my-kmp-app # 使用 IDEA 或 Android Studio 打开这个文件夹打开后IDE 会自动开始导入 Gradle 项目并下载依赖。项目结构解析创建一个库项目后你会看到类似如下的结构这是理解 KMP 和 Kotlin Toolchain 配置的关键my-kmp-library/ ├── build.gradle.kts # 项目的根构建脚本配置所有子模块的公共部分 ├── settings.gradle.kts # 定义项目包含哪些模块 ├── gradle/ │ └── wrapper/ # Gradle Wrapper 文件确保构建版本一致 ├── gradlew # Unix/Linux/macOS 的 Gradle 执行脚本 ├── gradlew.bat # Windows 的 Gradle 执行脚本 └── shared/ # 我们的共享模块核心 ├── build.gradle.kts # 共享模块的构建脚本配置 KMP 目标平台 ├── src/ │ ├── commonMain/ # 所有平台共享的代码和资源 │ ├── androidMain/ # Android 平台特定的代码 │ └── iosMain/ # iOS 平台特定的代码 └── ...核心配置文件shared/build.gradle.kts示例plugins { kotlin(multiplatform) // 应用 Kotlin 多平台插件 } kotlin { // 1. 声明目标平台 androidTarget() // 会自动应用 com.android.library 插件 iosX64() iosArm64() iosSimulatorArm64() // 2. 配置源代码集 sourceSets { val commonMain by getting { dependencies { // 公共依赖所有平台都能用 implementation(kotlin(stdlib-common)) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0) } } val androidMain by getting { dependencies { // Android 平台特定依赖 implementation(androidx.core:core-ktx:1.12.0) } } // ... 其他平台源代码集的依赖配置 } }这个配置完全基于 Kotlin DSL清晰定义了模块的目标平台和各平台的依赖关系是 Kotlin Toolchain 的核心体现。5. 从 Amper 项目迁移到 Kotlin Toolchain如果你有一个现有的 Amper 项目迁移是必要的。迁移的核心是将.amper目录下的 YAML 配置转换为标准的 Gradle Kotlin DSL 构建脚本。迁移步骤第 1 步备份与评估备份整个项目。评估项目复杂度简单的单模块库迁移较快复杂的多模块应用需要更多时间。第 2 步创建新的 Gradle 项目结构建议创建一个新的、基于模板的 Kotlin Toolchain 项目如上节所述而不是在原 Amper 项目上直接修改。这样可以获得一个干净的、正确的起点。将你原有的源代码src/目录下的内容从 Amper 项目复制到新项目对应的源代码集中commonMain,androidMain等。注意保持包结构。将资源文件、配置文件等一并复制。第 3 步转换依赖声明这是迁移中最关键的一步。你需要将 Amper YAML 中的依赖转换为 Gradle Kotlin DSL 的语法。Amper YAML 示例 (module.yaml):dependencies: - group: org.jetbrains.kotlinx name: kotlinx-coroutines-core version: 1.8.0 - platform: android dependencies: - group: androidx.core name: core-ktx version: 1.12.0对应的 Kotlin DSL (build.gradle.kts):kotlin { sourceSets { val commonMain by getting { dependencies { implementation(org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0) } } val androidMain by getting { dependencies { implementation(androidx.core:core-ktx:1.12.0) } } } }依赖类型映射:Amper 中的普通依赖 - Gradle 的implementationAmper 中的api依赖 - Gradle 的api(用于传递依赖)平台特定依赖 - 移动到对应平台的sourceSets中。第 4 步转换构建配置编译选项Amper 中的languageVersion等设置对应到 Kotlin DSL 中的kotlin块配置。kotlin { compilerOptions { languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0) } // ... 目标平台配置 }Android 配置如果 Amper 项目有 Android 配置需要在android块中设置compileSdk、namespace等。android { compileSdk 34 namespace com.yourcompany.library // ... }第 5 步测试与验证在 IDE 中同步 Gradle 项目通常点击Reload All Gradle Projects按钮。尝试编译各个目标平台# 编译所有目标 ./gradlew build # 仅编译公共代码 ./gradlew shared:compileCommonMainKotlinMetadata # 编译 Android 库 ./gradlew shared:compileDebugAndroidSources # 编译 iOS 框架 (需要在 macOS 上) ./gradlew shared:linkDebugFrameworkIosArm64运行单元测试./gradlew allTests迁移后你可以安全地删除原项目中的.amper目录和相关配置。6. Kotlin Toolchain 核心功能与日常操作成功创建或迁移项目后以下是你日常开发中会频繁使用的 Kotlin Toolchain 功能。6.1 管理多平台目标在shared/build.gradle.kts的kotlin块中你可以灵活地添加、移除或配置平台目标。kotlin { // 启用 JVM 目标用于后端或桌面 jvm() // 启用 JS 目标用于浏览器或 Node.js js(IR) { browser() // 针对浏览器 // nodejs() // 针对 Node.js } // 启用原生目标 macosX64() macosArm64() linuxX64() mingwX64() // Windows // 为所有 iOS 目标统一配置 iosTarget { binaries.framework { baseName MySharedFramework } } }每次修改目标后需要在 IDE 中重新同步 Gradle 项目。6.2 添加与配置依赖依赖管理是构建工具的核心。Kotlin Toolchain 使用 Gradle 的依赖声明并支持平台特定依赖。sourceSets { val commonMain by getting { dependencies { // Kotlin 标准库 implementation(kotlin(stdlib-common)) // 协程 implementation(org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0) // Ktor 客户端 (网络请求) implementation(io.ktor:ktor-client-core:2.3.10) } } val androidMain by getting { dependencies { implementation(io.ktor:ktor-client-android:2.3.10) } } val iosMain by getting { dependencies { implementation(io.ktor:ktor-client-darwin:2.3.10) } } val jvmMain by getting { dependencies { implementation(io.ktor:ktor-client-cio:2.3.10) } } }6.3 运行测试Kotlin Toolchain 使得运行跨平台测试变得简单。运行所有测试./gradlew allTests运行公共代码测试./gradlew shared:test运行 Android 单元测试./gradlew shared:testDebugUnitTest运行 iOS 测试需在 macOS./gradlew shared:linkDebugTestIosArm64(编译测试二进制文件然后在模拟器或设备上运行)你可以在commonTest、androidTest、iosTest等源代码集中编写平台相关的测试代码。6.4 构建与发布构建所有目标产物./gradlew build。这会在shared/build/libs/和shared/build/binaries/下生成 JAR、AAR、Framework 等文件。发布到 Maven Local用于本地测试./gradlew publishToMavenLocal发布后在其他本地项目中可以引用mavenLocal()仓库中的该库。发布到远程仓库需要配置maven-publish插件和仓库地址。// 在 shared/build.gradle.kts 中添加 plugins { maven-publish } publishing { publications { createMavenPublication(maven) { groupId com.yourcompany artifactId mylibrary version 1.0.0 from(components[kotlin]) } } repositories { maven { url uri(https://your.artifact.repo.url) credentials { username project.findProperty(repoUser) as String? password project.findProperty(repoPassword) as String? } } } }然后运行./gradlew publish。7. 性能优化与构建配置技巧随着项目增长构建速度可能变慢。以下是一些优化技巧1. 启用 Gradle 构建缓存和配置缓存在gradle.properties文件中项目根目录或用户家目录下的.gradle文件夹添加# 启用构建缓存 org.gradle.cachingtrue # 启用配置缓存 (Gradle 7.5) org.gradle.configuration-cachetrue # 并行执行任务 org.gradle.paralleltrue # 增加 JVM 堆内存 org.gradle.jvmargs-Xmx4096m -XX:MaxMetaspaceSize1024m2. 使用 Kotlin 增量编译确保 Kotlin 编译器选项已启用增量编译默认通常是开启的。3. 避免在配置阶段执行昂贵操作不要在build.gradle.kts的顶层或by getting块中执行文件 I/O、网络请求等操作。将这些逻辑移到doFirst、doLast或自定义任务中。4. 精确声明依赖使用implementation而非api除非你需要传递该依赖。使用runtimeOnly替代implementation对于仅运行时需要的依赖。为测试依赖使用testImplementation。5. 管理原生编译目标如果暂时不需要某个原生平台如watchosArm64可以先将其注释掉以加快配置和构建速度。8. 常见问题与排查方法在迁移或使用 Kotlin Toolchain 过程中你可能会遇到以下问题。问题现象可能原因排查方式解决方案Gradle 同步失败1. 网络问题导致依赖下载失败。2.build.gradle.kts中存在语法错误。3. Kotlin 或 Gradle 插件版本不兼容。1. 查看 IDEA 的 “Build” 工具窗口或运行./gradlew --info。2. 检查错误信息指向的文件和行号。1. 检查网络或使用国内镜像。2. 修正 Kotlin DSL 语法错误。3. 确保gradle/wrapper/gradle-wrapper.properties中的 Gradle 版本与插件兼容。参考官方兼容性矩阵。“Unresolved reference” 编译错误1. 依赖未正确声明。2. 依赖声明在了错误的源代码集。3. 使用了平台不支持的库。1. 检查build.gradle.kts中对应sourceSet的dependencies块。2. 确认库是否支持 KMP查看其文档。1. 添加正确的依赖坐标。2. 将依赖移动到正确的平台源代码集下。3. 对于不支持 KMP 的纯 JVM 库考虑使用expect/actual机制提供平台实现。iOS 编译失败1. 未在 macOS 上操作。2. Xcode 或命令行工具未安装/版本过旧。3. 签名或证书问题。1. 确认操作系统。2. 运行xcodebuild -version。3. 查看完整的错误堆栈。1. 必须在 macOS 上编译 iOS 目标。2. 安装/更新 Xcode 及命令行工具。3. 在 Xcode 中配置好开发者团队和签名证书。对于模拟器可能不需要签名。构建速度慢1. 未启用缓存。2. 依赖过多或版本冲突。3. 自定义任务配置低效。1. 检查gradle.properties。2. 运行./gradlew :shared:dependencies分析依赖树。1. 按照第 7 节启用缓存和并行。2. 使用implementation而非api移除未使用的依赖。3. 优化构建脚本。运行 iOS 模拟器失败1. 模拟器未启动或设备 ID 不对。2. Framework 构建配置错误。1. 检查iosSimulatorArm64目标是否正确配置。2. 查看 Gradle 错误信息。1. 确保在运行任务前启动正确的模拟器。2. 使用./gradlew :shared:linkDebugFrameworkIosSimulatorArm64构建并通过 Xcode 项目或xcodebuild命令运行。迁移后代码找不到1. 源代码复制到了错误的目录。2.sourceSets配置被意外修改。1. 核对项目结构确保代码在src/commonMain/kotlin等正确路径下。2. 检查build.gradle.kts中的sourceSets块。1. 按照标准 KMP 项目结构重新放置源代码。2. 如果自定义了源集确保配置正确。9. 最佳实践与使用建议为了确保项目长期健康遵循以下最佳实践从模板开始始终使用官方或社区验证过的模板创建新项目避免从零开始配置的繁琐和错误。锁定版本在gradle/libs.versions.toml文件或build.gradle.kts的extra属性中集中管理依赖版本避免冲突。善用expect/actual这是 KMP 的精髓。将平台相关的 API如文件 I/O、网络、UI在commonMain中声明为expect然后在各平台源代码集中提供actual实现。模块化设计对于大型项目将代码拆分为多个 KMP 模块每个模块职责单一。这能提升构建速度和代码可维护性。持续集成在 CI/CD 流水线中为所有目标平台运行构建和测试。确保代码变更不会意外破坏某个平台的兼容性。关注社区Kotlin 和 KMP 生态发展迅速。关注官方博客、Kotlin Slack 频道和 GitHub 仓库及时了解新特性和最佳实践的更新。性能剖析定期使用 Gradle Build Scan 或使用--profile参数运行构建分析构建瓶颈并加以优化。JetBrains 将未来押注在 Kotlin Toolchain 上这是一个明确的信号。对于开发者而言尽早拥抱这个官方标准工具链意味着更少的迁移痛苦、更好的生态兼容性和更持续的技术支持。虽然从 Amper 的 YAML 迁移到 Gradle Kotlin DSL 需要一些学习成本但这份投资是值得的它为你打开了整个成熟的 Gradle 生态和 KMP 全部能力的大门。建议你现在就创建一个基于 Kotlin Toolchain 的示例项目按照本文的步骤跑通编译、测试和运行流程。在实战中熟悉了这套工具链后无论是开发新项目还是迁移旧项目你都将更加得心应手。