Mirai 多平台项目配置指南在 Kotlin Multiplatform 项目中集成 mirai-core【免费下载链接】mirai高效率 QQ 机器人支持库项目地址: https://gitcode.com/gh_mirrors/mi/mirai本篇技术指南以 mirai 官方文档 ConfiguringMultiplatformProjects.md 为核心骨架系统讲解如何在 Kotlin MultiplatformKMP项目中以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 ...。发布平台名称描述jvmJVMandroidAndroid (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.0mirai 的多平台产物依赖 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等jvmBaseMainJVM 与 Android 共享的中间源集hierarchical source set依赖netty-handler、log4j-api、kotlinx-coroutines-jdk8androidMainAndroid 专属源集当 Android 目标 API 低于 23 时额外引入bouncycastle因低版本 AndroidKeyStore 不够稳定参见 mirai-core/build.gradle.kts 及其中注释指向的EcdhAndroidKtjvmMainJVM 专属源集引入bouncycastle与网络实现相关依赖。这种commonMain → jvmBaseMain → {jvmMain, androidMain}的层级关系由 buildSrc/src/main/kotlin/HmppConfigure.kt 中的configureJvmTargetsHierarchical统一配置。对你而言这意味着你在commonMain中编写的代码天然可以在 JVM 与 Android 两端复用Kotlin 会根据你声明的目标平台自动为jvmMain、androidMain选择 mirai 对应的平台变体。仓库自身的构建还启用了大量多平台特性可作为排错时的参考见 gradle.properties如kotlin.incremental.multiplatformtrue、kotlin.mpp.androidSourceSetLayoutVersion2、mirai.android.target.api.level21mirai 的 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 groupIdnet.mamoe/groupId artifactIdmirai-core-jvm/artifactId version2.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 版本信息便于维护者复现。依赖配置完成后就可以进入下一阶段阅读 mirai-core 开发文档开始编写你的多平台机器人代码了。依赖配置完成回到 Mirai 文档索引 继续查阅其他章节。【免费下载链接】mirai高效率 QQ 机器人支持库项目地址: https://gitcode.com/gh_mirrors/mi/mirai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考