MaaYuan Docs

切换主题

快速开始关于MaaYuan功能介绍任务介绍常见问题开发手册

常见问题必读 ​

TIP

第一次使用 MaaYuan 时，建议先看 下载与安装 与 首次启动。如果还是有问题，再来查这份 FAQ。

一、不会处理时先做什么 ​

  1. 先确认 MaaYuan 是否为最新版本。
  2. 优先检查运行库、分辨率、触控方式和连接地址。
  3. 导出 debug/maa.log 后再反馈。
  4. 如果只是想先快速定位，也可以把日志交给 AI 辅助分析。

二、下载 / 安装问题 ​

下载哪个安装包 ​

  • 目前只支持两种安装包：MaaYuan-win-x86_64-vXXX.zip 与 MaaYuan-macos-aarch64-vXXX.tar.gz
  • Windows 仅支持 x64，不支持 Windows ARM
  • macOS 仅支持 Apple Silicon（aarch64），不支持 Intel Mac
  • Linux、Android、iOS 与其他未知平台当前均不支持

运行库问题 ​

  • 先确认是否已安装正确的 .NET 10 运行库
  • Windows 可能还需要补装 VCRedist

系统问题 ​

  • 不支持 32 位系统
  • 不支持 Windows 7 / 8 / 8.1
  • 若系统组件损坏，可能只能重装系统

更新版本出现问题 ​

  1. 彻底关闭 MaaYuan。
  2. 打开任务管理器结束所有 adb 进程。
  3. 仍失败时，直接删除旧版本并解压最新完整包。

三、启动问题 ​

常见报错与对应方向 ​

报错优先处理方向
MFA 遇到了问题先回看运行库与系统环境
无法加载 DLL确认在解压后的原目录中运行
此应用无法在你的电脑上运行多半是下错架构包
XX 异常常见于 .NET 运行库不完整
未能加载文件系统版本过旧
检测资源...错误检查网络、DNS 或相关代理工具

启动 Agent 无进展 ​

  • 常见原因是仍在安装依赖库，请先等一会儿。
  • 如果长时间无进展：
    • 重启再试
    • 重新下载完整包
    • 使用“重新下载资源全量包”
    • Mac 用户优先排查系统安全限制

依赖安装失败 ​

可改为手动安装，示例命令形如：

sh
D:\MaaYuan-win-x86_64-v0.9.13-beta.7\python\python.exe -m pip install maafw pandas openpyxl loguru opencv-python zhconv -i https://pypi.tuna.tsinghua.edu.cn/simple

如果镜像不可用，可替换为其他源，例如：

txt
https://mirrors.aliyun.com/pypi/simple

四、连接错误 ​

基础检查 ​

  1. 先自行安装并打开模拟器。
  2. 关闭模拟器后台保活。
  3. 更新到较新的模拟器版本。
  4. 先手动进入游戏并停在可见头像与昵称的页面，再打开 MaaYuan。

ADB 被占用或连接不上 ​

  • 关闭手机助手及类似后台
  • 检查是否被其他 MaaYuan 或游戏实例占用
  • 在任务管理器里结束所有 adb 相关进程

端口被占用怎么查 ​

sh
netstat -aon|findstr 5037
netstat -aon|findstr 5555

找到末尾的 PID 后，可在任务管理器中定位并结束可疑进程。

自动连接检测失败 ​

  • 先尝试以管理员权限启动 MaaYuan
  • 仍失败就改用手动设置
  • 自定义连接时确认 ADB 路径、端口和地址完全正确

自定义连接建议 ​

  1. 下载 platform tools 并解压到全英文路径。
  2. 在 MaaYuan 中手动导入 adb.exe。
  3. 手动填写连接地址。
  4. 用自定义连接时不要再点“刷新”。

五、运行问题 ​

运行任务后无反应或一直乱点 ​

  • 重启 MaaYuan
  • 检查多开端口是否对应正确实例
  • 关闭后台保活
  • 确认分辨率为 720 × 1280
  • 切换触控方式重试

6-24 / 7-15 失败 ​

  • 先确认分辨率
  • 确认已解锁相关章节并停在正确入口
  • MuMu 用户记得关闭后台保活
  • DPI 建议不低于 180
  • 必要时关闭 GPU 加速

截图耗时过长 / 触控慢 ​

  • 截图用时 ≤1000ms 通常属于正常范围
  • 可以尝试 GPU 加速推理
  • 但老旧显卡或核显不建议强开

启动游戏无法运行 ​

  • 根据游戏语言选择正确资源类型
  • 港服务必确认语言与客户端版本是否对应
  • 如果只是手动开游戏，不一定非要勾选“启动游戏”任务

六、作业问题 ​

资源加载失败 ​

  • 作业文件要放在 resource\copilot-cache
  • 推荐优先使用神秘代码导入
  • 删除有问题的作业后重启，如仍异常可直接更新到最新版本

神秘代码导入失败 ​

  • 多数情况是网络问题
  • 可稍后重试，或改为下载 JSON 本地导入

抄作业失败 ​

  • 0s 结束：通常是作业未激活
  • 10~20s 左右结束：通常是开始页面不对，未识别到关键 UI
  • 导入后无法连接或提示资源加载失败：优先同时检查 MaaYuan 版本与作业生成时间

打到第七回合自动结束 ​

  • 检查是否勾选了“抄完几回合后自动停止”
  • 调整分辨率到 720 × 1280
  • 不行的话改为“战斗中开始抄作业”模式

七、其他问题 ​

管理员权限说明 ​

通常不需要管理员权限，但以下情况除外：

  • 模拟器以管理员身份运行
  • 安装路径没有写入权限
  • 某些自动检测或关闭模拟器操作被系统拦截

WARNING

如果你已经清理过运行库、分辨率、ADB、作业目录这些高频问题，仍然无法解决，请按 反馈方式 中的步骤导出 maa.log 后再反馈。

MaaYuan 为免费开源项目，欢迎前往 GitHub 关注文档更新。

MaaYuan Docs · Built with VitePress