1. 项目概述最近在折腾一个跨平台的QQ机器人项目发现Mirai框架确实是个不错的选择。这个开源框架支持Linux、Windows和MacOS三大平台我用CentOS和Windows10都成功部署过。下面就把我的踩坑经验完整分享出来包括环境配置、账号登录、插件安装等全流程。QQ机器人现在应用场景很多比如自动回复、群管理、内容推送等。Mirai作为目前最活跃的开源框架之一更新维护都很及时社区生态也不错。最关键的是它跨平台特性很好在不同系统上部署差异很小。2. 环境准备2.1 Linux环境配置建议使用Ubuntu 22.04或CentOS 7.6以上版本。先安装基础工具# Ubuntu/Debian sudo apt update sudo apt upgrade -y sudo apt install -y unzip screen wget vim # CentOS/RHEL sudo yum install -y unzip screen wget vimscreen工具很重要可以保持会话不中断。建议新手都装上后面启动机器人时会用到。2.2 JDK17安装Mirai需要Java环境推荐用JDK17# Ubuntu一键安装 sudo apt install -y openjdk-17-jdk # CentOS手动安装 wget https://d6.injdk.cn/openjdk/openjdk/17/openjdk-17.0.1_linux-x64_bin.tar.gz tar zxf openjdk-17.0.1_linux-x64_bin.tar.gz sudo mv jdk-17.0.1 /usr/local/jdk-17配置环境变量echo export JAVA_HOME/usr/local/jdk-17 ~/.bashrc echo export PATH$JAVA_HOME/bin:$PATH ~/.bashrc source ~/.bashrc验证安装java -version2.3 Windows环境配置Windows用户直接下载JDK17安装包访问Oracle官网下载Windows x64 Installer默认选项安装即可在cmd验证java -version3. Mirai核心部署3.1 下载MCL启动器MCL是Mirai的官方启动器简化了很多操作mkdir mcl cd mcl wget https://ghproxy.com/https://github.com/iTXTech/mirai-console-loader/releases/download/v2.1.2/mcl-2.1.2.zip unzip mcl-2.1.2.zipWindows用户直接下载zip解压运行mcl.cmd即可。3.2 首次启动配置java -jar mcl.jar首次启动会自动下载依赖看到mirai-console started successfully就成功了。这时先输入stop退出。3.3 账号登录配置修改AutoLogin.ymlvim config/Console/AutoLogin.yml内容改为configuration: protocol: MACOS device: device.json enable: true heartbeatStrategy: STAT_HB安装协议修复插件wget -P plugins/ https://ghproxy.com/https://github.com/cssxsh/fix-protocol-version/releases/download/v1.5.0/fix-protocol-version-1.5.0.mirai2.jar4. 登录与验证4.1 处理滑块验证重新启动后会遇到滑块验证java -jar mcl.jar按照提示用Chrome打开验证链接F12打开开发者工具 - Network完成滑块后找到cap_union_new_verify请求复制ticket值粘贴回终端4.2 设备锁验证可能还会遇到设备锁手机QQ确认登录终端输入收到的验证码看到Login successful即成功5. 插件生态5.1 基础插件推荐Chat-Command聊天环境执行指令Grass-Pic随机图片推送DouDiZhuQQ斗地主游戏WeiboHelper微博内容转发安装方法wget -P plugins/ [插件下载链接]5.2 插件配置示例以斗地主插件为例添加游戏群/dc addgroup 123456789添加管理员/dc addadmin 9876543216. 运维管理6.1 后台运行方案使用screen保持会话screen -S mcl java -jar mcl.jar # CtrlA D 退出会话 # 恢复会话screen -r mcl6.2 常见问题排查登录失败检查协议版本更新fix-protocol插件消息发送失败检查账号是否被限制插件冲突逐个禁用排查7. 进阶配置7.1 权限管理系统Mirai有完善的权限控制# 给用户权限 /perm add u123456 xyz.plugin:command # 给群权限 /perm add m789012 xyz.plugin:command7.2 自定义开发可以用Java/Kotlin开发自定义插件参考mirai-console文档使用mirai-core API打包为jar放入plugins目录8. 注意事项避免高频操作容易触发风控建议用小号部署主号有封禁风险定期备份config目录Windows防火墙要放行Java云服务器注意安全组规则这个方案我在三台服务器和本地Win10都测试过目前运行稳定。最大的坑其实是QQ的滑块验证建议准备一个常用IP。如果遇到其他问题可以查看Mirai官方文档或社区讨论。