Mirai 多平台项目配置指南：在 Kotlin Multiplatform 项目中集成 mirai-core-平芜编程栈

Mirai 多平台项目配置指南：在 Kotlin Multiplatform 项目中集成 mirai-core

【免费下载链接】mirai高效率 QQ 机器人支持库项目地址: https://gitcode.com/gh_mirrors/mi/mirai

本篇技术指南以 mirai 官方文档 ConfiguringMultiplatformProjects.md 为核心骨架，系统讲解如何在 Kotlin Multiplatform（KMP）项目中以mirai-core作为依赖库接入 QQ 机器人能力。你将掌握受支持的编译目标平台边界、commonMain依赖配置方法、版本与工具链要求，并结合本仓库源码理解 mirai 的多平台模块划分与发布机制，从而在自己的 KMP 工程中正确、稳定地完成依赖集成与问题排查。

选择版本

在开始配置依赖之前，请先确定使用哪个版本的 mirai。版本选择的基本原则可参考 JVM 项目配置指南的「选择版本」小节：mirai 的版本分为稳定版、预览版与开发快照三类，通常建议选择最新稳定版本。

稳定版与预览版：通过 GitHub Releases 发布，可查看 mirai 各版本发布说明中的变更记录；
开发快照：每日构建的最新开发版本，用法参见 UsingSnapshots.md。

关于 mirai 的版本命名规范（如2.x.y、-M、-RC后缀的含义），可阅读 Evolution.md。注意文档中的示例版本号可能滞后于当前最新版本，请以你在 Maven Central 上查询到的最新稳定版本为准。

支持的编译目标平台

mirai 通过 Kotlin Multiplatform 进行构建，并将预编译产物上传至 Maven Central。只有在下表列出的平台上，你的 KMP 项目才能直接消费 mirai 的预编译模块；如果你使用了不支持的平台，构建时将会收到来自 Gradle 的依赖解析错误（如 "could not resolve net.mamoe:mirai-core for variant ..."）。

发布平台名称	描述
jvm	JVM
android	Android (Dalvik)

平台支持历史（重要变更）：mirai 曾在2.13.0至2.15.0-RC（不含）之间支持编译到 macOS、Windows、Linux 等桌面原生平台；自2.15.0-RC起已完全删除对这些平台的支持。因此如果你使用的是较新版本，KMP 工程中请勿声明linuxX64、macosX64、mingwX64等原生目标来消费 mirai。

这一平台边界的设定与本仓库的实际构建配置一致：在 mirai-core/build.gradle.kts 中，核心模块仅通过configureJvmTargetsHierarchical("net.mamoe.mirai.internal")声明了 JVM 与 Android 两类目标（jvm与android），其二进制兼容性验证文件也只覆盖jvm与android两个变体（见 mirai-core/compatibility-validation 下的jvm/api/jvm.api与android/api/android.api）。

添加依赖

在 KMP 工程中集成 mirai 非常简单：只需为commonMain源集添加依赖即可，Kotlin 插件会自动为其他源集（如jvmMain、androidMain）推导并配置对应的平台依赖。

工具链版本要求

Kotlin 编译器版本必须至少为1.7.0：mirai 的多平台产物依赖 Kotlin 1.7+ 的元数据格式与层级源集（hierarchical source sets）能力；
Gradle 版本建议高于7.3：更旧的 Gradle 可能无法正确解析 Kotlin Multiplatform 模块的变体。

作为参照，本仓库自身构建所使用的关键依赖版本可在 buildSrc/src/main/kotlin/Versions.kt 中查看：kotlinCompiler = 1.8.10、coroutines = 1.6.4、serialization = 1.5.0，这说明 mirai 的构建产物是针对 Kotlin 1.8 时代的多平台体系产出的，使用较新的编译器消费时通常具有更好的兼容性。

最小可运行配置

以下是一个可直接复制到build.gradle.kts的最小配置（示例版本号建议按上文「选择版本」更新）：

plugins { kotlin("multiplatform") version "1.7.20" } kotlin { sourceSets { val commonMain by getting { dependencies { implementation("net.mamoe:mirai-core:2.13.0") implementation("net.mamoe:mirai-core-utils:2.13.0") } } } }

关于mirai-core-utils：额外添加net.mamoe:mirai-core-utils是为了临时解决 issue #2275（多平台环境下某些场景的传递依赖解析问题）。在 mirai 2.13.x 时代这是官方推荐的规避写法；如果后续版本已修复该问题，这一行可以被移除。需要注意，mirai-core与mirai-core-utils的版本号务必保持一致，避免因版本不匹配引发运行时异常。

分离 API 与实现（可选优化）

与 JVM 项目配置相同，多平台项目中同样可以分离 API 与实现：开发与编译时只依赖net.mamoe:mirai-core-api，运行时再引入net.mamoe:mirai-core，从而减轻 IDE 的索引负担。自2.8.0起，mirai 还提供了net.mamoe:mirai-bom用于自动协调各组件版本，这是官方推荐的首选方式：

kotlin { sourceSets { val commonMain by getting { dependencies { api(platform("net.mamoe:mirai-bom:2.13.0")) // BOM 统一版本 api("net.mamoe:mirai-core-api") // 编译代码使用 runtimeOnly("net.mamoe:mirai-core") // 运行时使用 } } } }

BOM 的生成机制见 mirai-bom/build.gradle.kts：它遍历所有子项目，将每个子项目发布的 Maven 坐标（groupId:artifactId:version）以constraints形式汇总成一个 Java Platform，因此能保证mirai-core、mirai-core-api、mirai-core-utils等组件版本自动对齐，对 Dependabot 等自动化依赖管理工具也更友好。

深入理解：mirai 的多平台源码结构与依赖流向

要在多平台项目中用好 mirai，理解其内部源码集的划分会非常有帮助。从 mirai-core/build.gradle.kts 可以看到核心模块的依赖组织：

commonMain：声明与平台无关的公共 API，包括kotlinx-serialization-core/json、kotlinx-coroutines-core、kt-bignum、mirai-core-utils等；
jvmBaseMain：JVM 与 Android 共享的中间源集（hierarchical source set），依赖netty-handler、log4j-api、kotlinx-coroutines-jdk8；
androidMain：Android 专属源集，当 Android 目标 API 低于 23 时额外引入bouncycastle（因低版本 AndroidKeyStore 不够稳定，参见 mirai-core/build.gradle.kts 及其中注释指向的EcdhAndroidKt）；
jvmMain：JVM 专属源集，引入bouncycastle与网络实现相关依赖。

这种commonMain → jvmBaseMain → {jvmMain, androidMain}的层级关系由 buildSrc/src/main/kotlin/HmppConfigure.kt 中的configureJvmTargetsHierarchical统一配置。对你而言，这意味着：你在commonMain中编写的代码天然可以在 JVM 与 Android 两端复用，Kotlin 会根据你声明的目标平台自动为jvmMain、androidMain选择 mirai 对应的平台变体。

仓库自身的构建还启用了大量多平台特性，可作为排错时的参考（见 gradle.properties）：如kotlin.incremental.multiplatform=true、kotlin.mpp.androidSourceSetLayoutVersion=2、mirai.android.target.api.level=21（mirai 的 Android 目标 API 级别为 21）等。

发布产物与 artifactId 命名规则

如果你需要在 Maven 或 Gradle 中直接引用 mirai 的某个平台变体（例如在传统 JVM 工程中），需要了解其 artifactId 的命名规则。从 buildSrc/src/main/kotlin/MppPublishing.kt 可以看到：

根模块kotlinMultiplatform发布为mirai-core（不含平台后缀）；
平台模块则以-<平台名>后缀命名，如mirai-core-jvm；
元数据模块使用-metadata后缀。

因此，在 Maven 中引用 JVM 变体时应写成：

<dependencies> <dependency> <groupId>net.mamoe</groupId> <artifactId>mirai-core-jvm</artifactId> <version>2.13.0</version> </dependency> </dependencies>

注意：在 Maven 中 artifactId 必须使用带-jvm后缀的变体；而在 KMP 工程的commonMain中则直接使用不带后缀的mirai-core，由 Gradle 依据平台属性自动完成变体选择。

此外，mirai 的 JVM 产物在发布时经过了依赖重定位（shadow relocation）处理（见 MppPublishing.kt 中的useRelocatedPublication与 buildSrc/src/main/kotlin/shadow/Relocation.kt）：像 Ktor、Netty 等内部依赖会被重定位到net.mamoe.*命名空间并从 POM 中剔除，从而避免与你项目中的同名依赖冲突。这也是多平台/JVM 集成中很少出现依赖冲突的原因之一。

解决问题

如果你在使用多平台项目时遇到问题，那应该是正常的——Kotlin 多平台在 1.7 时代仍属于测试版功能，其变体解析、元数据兼容性都可能产生意料之外的报错。以下排查建议按优先级排列：

核对工具链版本：确认 Kotlin 编译器 ≥ 1.7.0、Gradle > 7.3，这是多平台依赖解析正常工作的前提；
核对目标平台：确认工程声明的目标仅包含jvm与android（新版 mirai 不再支持桌面原生目标）；
核对版本一致性：mirai-core、mirai-core-api、mirai-core-utils的版本必须一致，优先使用mirai-bom统一管理；
检查mirai-core-utils是否缺失：若复现 issue #2275 相关的解析错误，请参照上文补上该依赖；
查询依赖解析详情：运行./gradlew dependencies或对具体配置执行dependencyInsight，定位到底是哪个变体解析失败；
反馈上游：欢迎在 mirai 仓库的 issues 中提交多平台相关问题，附上完整的build.gradle.kts与 Gradle 版本信息，便于维护者复现。