MaaDebugger

由 MaaXYZ 团队开发与维护的 MaaFramework 调试器，拥有现代的 WebUI 和即时的任务反馈。

Official desktop debugger for MaaFramework, featuring a web-based UI and real-time task inspection.

安装方式

使用 npm (Node.js)

MaaDebugger 暂时以 @weinibuliu/maa-debugger 的名称发布于 npm 。你可以使用 npm 或其他包管理器(如 pnpm)安装、管理与使用。这里仅介绍 npm 与 pnpm 用法。

npm

npx @weinibuliu/maa-debugger@latest

pnpm

pnpm dlx @weinibuliu/maa-debugger@latest

MaaDebugger 支持命令行参数，你可以通过 --help / -H 命令来获取帮助。

npx @weinibuliu/maa-debugger --help

使用 pip (Python)

MaaDebugger 将以 MaaDebugger 的名称发布于 PyPI 。你可以使用 pip 或其他包管理器(如 uv)安装、管理与使用。

[!WARNING] 在早期开发阶段，我们不会发布至 PyPI，请自行使用其他渠道。

自行下载

我们也提供了 Github Release 下载渠道，下载解压后即可使用。

[!WARNING] 在早期开发阶段，我们不会发布至 Github Release，而是仅在 Actions 上传产物，请自行前往下载。

开发模式

在开发阶段需要同时启动后端和前端两个终端：

Terminal 1: 后端 (Go Service)

cd server
air # 支持热重载

Terminal 2: 前端 (Web)

cd web
pnpm i   # 首次需要安装依赖
pnpm dev        # 启动前端 (http://localhost:5173)

然后打开浏览器访问 http://localhost:5173 即可。

前端会自动将 /api 和 /ws 请求代理到后端 http://127.0.0.1:8011。

生产构建

一键构建前端并嵌入到 Go 二进制文件中，最终产物为单个可执行文件：

node build.mjs                     # 构建当前平台
node build.mjs --os linux          # 交叉编译 Linux
node build.mjs --os windows        # 交叉编译 Windows
node build.mjs --os darwin         # 交叉编译 macOS
node build.mjs --skip-frontend     # 跳过前端构建（仅编译 Go）
node build.mjs --skip-go           # 跳过 Go 编译（仅构建前端）

构建完成后，启动 ./MaaDebugger（Windows 下为 ./MaaDebugger.exe），程序会自动选择可用端口（默认从 8011 开始）并打开浏览器。

[!NOTE] 需要注意的是 MaaDebugger 将寻找 ./bin 下的 MaaFramework 动态库。