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），仅供参考
企业数字化 ERP 产品动态
相关推荐
3个坑搞定火花探测，一文搞懂前端实战逻辑 3个坑搞定火花探测，一文搞懂前端实战逻辑 刚学完 JavaScript 语法，对着文档敲代码挺顺，但让你搭个完整项目，脑子瞬间空白？别慌，这种“会写语句但不会拼项目”的尴尬，90% 的前端新手都经历过。今天不聊虚的，直接拿 火花探测… · 2026/9/22 9:30:04
快手视频在线解析新手避坑：3个致命错误教你少踩雷 快手视频在线解析新手避坑：3个致命错误教你少踩雷 面试被问原理答不上来，是不是因为你只懂调用API，连底层数据流都没搞明白？别慌，今天这篇新手避坑指南，专治各种“只会调包不会排查”的毛病。 现象：接口突然失效，返回403或空数据… · 2026/9/22 9:29:58
远程控制系统卡顿？3步性能优化让响应快10倍 远程控制系统卡顿？3步性能优化让响应快10倍 昨天调试一个工业设备远程控制脚本，复制来的代码在本地跑飞了，但一到生产环境就卡成PPT。最崩溃的是，报错信息模糊不清，根本不知道是网络延迟、线程阻塞还是序列化开销大。这种“复制即死”的代码，不经… · 2026/9/22 9:29:58
号码之家源码拆解：从入门到精通避坑指南 号码之家源码拆解：从入门到精通避坑指南 看了一堆教程还是不会写项目？这是很多开发者卡在“入门到精通”门槛前的真实写照。特别是面对像【号码之家】这种涉及复杂状态流转、高并发校验的业务系统时，光懂语法没用，得看懂它底层怎么跑。… · 2026/9/22 10:05:41
地下城与勇士 缔造者避坑指南：从报错堆栈到高效开发 地下城与勇士 缔造者避坑指南：从报错堆栈到高效开发 面对满屏红色的 StackTrace，你是不是也一脸懵？那些嵌套的异常信息像天书一样，让人无从下手。别急，这份地下城与勇士 缔造者避坑指南能帮你快速定位问题，少走弯路。 很多新手在接触… · 2026/9/22 10:05:41
玩伴拼音配置卡半天?3个坑点+完整示例秒解 玩伴拼音配置卡半天?3个坑点+完整示例秒解 刚接手新需求，想把“玩伴”这两个字的拼音提取出来用于搜索索引或语音播报，结果配置环境就卡半天。要么库版本冲突报错，要么中文编码乱码，要么就是死活不出结果，折腾两小时才搞定。这种看似简单的需求，其实… · 2026/9/22 10:05:22
3招搞定pc单机游戏下载基地性能优化卡壳难题 3招搞定pc单机游戏下载基地性能优化卡壳难题 配置环境就卡半天，这种折磨谁懂？装个像《赛博朋克2077》这种大型pc单机游戏下载基地里的游戏，下载完还要解压、打补丁、配显卡驱动，折腾两小时还没跑起来。更坑的是，明明硬件达标，游戏却卡成PPT… · 2026/9/22 10:05:22
3个坑教你cad怎么加粗线条：手写实现底层逻辑 3个坑教你cad怎么加粗线条：手写实现底层逻辑 面试被问原理答不上来？别慌，很多老手也卡在“为什么线型不显示”或“打印出来还是细线”。今天咱们不背概念，直接上手 手写实现 一个最小化 CAD 线条渲染引擎。通过从零搭建项目，彻底搞懂… · 2026/9/22 10:05:15
国都兴业源码深扒：3步搞定核心逻辑的保姆级教程 国都兴业源码深扒：3步搞定核心逻辑的保姆级教程 官方文档翻了三遍还是云里雾里？别急，这篇保姆级教程带你直击源码核心。 做开发久了，谁都遇到过这种场景：接手一个老旧或特定行业的中间件项目，比如“国都兴业”相关的支付或清结算模块。打开IDE，满… · 2026/9/22 10:05:15
5个电影海报图片处理坑，新手避坑指南 5个电影海报图片处理坑，新手避坑指南 刚写完代码，一运行屏幕直接炸了。满屏红色的 StackTrace 滚得比弹幕还快，什么 NullPointerException 、 ImageIO.read() returned null 、… · 2026/9/22 0:00:07
注册微信公众账号：一文搞懂从0到1全流程 注册微信公众账号：一文搞懂从0到1全流程 复制来的代码跑不通，报错信息满屏飞，到底卡在哪？别急，咱们先停下手里的调试。很多开发者觉得注册微信公众账号只是填个表单、传个身份证那么简单，真上手才发现坑深不见底。今天这篇 一文搞懂… · 2026/9/22 0:00:07
