NapCatQQ基于 NTQQ 的 OneBot 协议端本地跑通 QQ 机器人的最短路径【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQNapCatQQ 是一个基于 NTQQ 的机器人协议端框架它把 NTQQ 的协议能力封装成标准 OneBot API 和 Web 管理界面适合需要在 Windows 上以低内存占用跑长期在线 QQ 机器人的开发者。如果你要对接现有 OneBot 框架如 AstrBot、MaiBot或者想读懂协议端内部实现这个项目都能直接用。3 分钟看懂仓库结构一句话定位NapCatQQ 是协议端不是应用框架——它负责登录、收发、暴露 API业务逻辑由你接入的 Bot 框架处理。仓库是 pnpm monorepo见 pnpm-workspace.yaml所有子包都在 packages/ 下模块作用packages/napcat-core/NTQQ 协议核心消息、群组、文件、事件监听、网络包packages/napcat-onebot/OneBot 标准 API 与事件实现HTTP/WebSocket 网络层packages/napcat-webui-backend/ 与 packages/napcat-webui-frontend/Web 管理界面的后端服务与 React 前端packages/napcat-shell/打包入口把核心与 WebUI 组装成可运行的 shellpackages/napcat-develop/开发调试用启动器加载本地已安装的 QQ新手先关注两块napcat-onebot定义了你能调用的全部 APInapcat-onebot/action/下按 user、group、msg、file 等目录分门别类翻一遍就知道能做什么。最短路径跑起来前置条件Node.js ≥ 18.0.0各包engines字段均要求、pnpm以及一台装有 NTQQ 客户端的 Windows 机器——开发模式启动脚本 packages/napcat-develop/nodeTest.ps1 会读取注册表里的 QQ 安装路径。git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install装完后packages/下各子包应都有node_modules链接说明 workspace 解析正常。pnpm run build:shell成功后会在packages/napcat-shell/dist/生成napcat.mjs无报错即通过。pnpm run dev:shell这个命令实际执行pnpm --filter napcat-develop run dev流程是脚本打印QQPath: ...定位到本机 QQ 目录把wrapper.node、QQNT.dll等运行时文件复制到packages/napcat-develop/dist/然后以--inspect调试模式加载 shell。看到文件复制完成、进程未退出即启动成功此时可用浏览器访问本地 WebUI默认 6099 端口凭据见下文配置节。各核心组件的分工napcat-core整个项目的地基。listeners/下是 QQ 事件的监听入口services/是一一对应 NodeI 接口的服务实现packet/处理网络包收发。排查协议层问题从这里入手。napcat-onebot把 core 的能力翻译成 OneBot 动作与事件。你对接 Bot 框架时实际消费的 API 全在action/与event/两个目录网络接入方式HTTP、WebSocket、SSE、客户端模式在network/下实现。napcat-webui-backend / frontend管理界面。日志、配置编辑、多账号管理走这条链路改界面行为看 frontend改接口看 backend 的router/。napcat-shell 与 napcat-framework前者是本地 shell 形态后者构建面向 GUI 集成的框架产物日常开发碰 shell 即可。napcat-protobuf / napcat-databaseprotobuf 消息定义与本地数据库读取的底层工具包一般不需要动。两处必改的配置OneBot 网络配置在 packages/napcat-develop/config/onebot11.json开发模式下build:shell:config会把它复制到 shell 产物目录。默认启用 HTTP127.0.0.1:3000和 WebSocket127.0.0.1:3001两个 servermessagePostFormat决定消息体是array还是string格式——对接框架时若收不到消息先核对这两项和框架端的约定是否一致。token字段用于接入鉴权生产环境务必填。WebUI 配置在 packages/napcat-webui-backend/webui.jsonhost/port控制访问地址默认 0.0.0.0:6099token是登录令牌开发模式固定为napcatqq。accessControlMode与黑白名单控制远程访问仅内网自用时保持none即可。按症状自查现象pnpm install 失败→ 常见原因是无法访问 npm registry 或网络抖动。确认网络能连通仓库源必要时换国内镜像源仍失败可执行pnpm store prune清理缓存后重装。现象build:shell 或 typecheck 报错→ 多为 TypeScript 配置或子包依赖版本问题。根目录 tsconfig.base.json 是全仓编译基准target ES2021、bundler 解析、strict子包各自有独立 tsconfig。看第一个报错的文件定位是哪个子包必要时单独跑pnpm --filter 包名 run typecheck缩小范围。现象dev:shell 报找不到 QQ 路径→nodeTest.ps1依赖 Windows 注册表中的 QQ 卸载信息定位安装目录QQ 未安装或安装在非常规位置都会失败。手动确认versions目录存在且包含resources/app子目录否则以仓库文档为准。现象服务起来了但框架收不到消息→ 依次核对 onebot11.json 的端口与messagePostFormat、token 是否两端一致、对应 server 的enable是否为 true。接下来做什么读 packages/napcat-onebot/action/ 下的动作实现挑msg/SendMsg.ts、group/GetGroupList.ts两个典型文件看参数与返回结构。跑 packages/napcat-test/ 里的用例pnpm run test其中 packages/napcat-test/Readme.md 说明了测试用途。需要 WebUI 侧细节时看 packages/napcat-webui-backend/Readme.md。对接具体 Bot 框架时在仓库 Issues 区搜同类项目README 提到 AstrBot、MaiBot 均为适配对象以仓库文档为准。【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考