NapCatQQ完整指南：从零开始搭建基于NTQQ的QQ机器人开发平台

【免费下载链接】NapCatQQ Modern protocol-side framework based on NTQQ 项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ

NapCatQQ 是一个基于 NTQQ 的现代化 QQ 机器人协议端框架。如果你想在新一代 NTQQ 平台上跑一个稳定、低占用的机器人，又不想自己啃协议细节，它把「登录、收发消息、群管理、文件传输、OneBot 11 接口」全部打包好了——你只需要关注业务逻辑本身。

📍 项目定位：为什么选择 NapCatQQ

NapCatQQ 采用 pnpm workspaces 组织的 monorepo 架构，把复杂能力拆成可独立构建的模块，同时通过统一的配置与类型层保证整体一致。

• 现代化技术栈：TypeScript 全量开发，Vite 构建，pnpm 管理多包
• 完整 OneBot 11 实现：标准动作（action）+ 事件推送，兼容常见机器人框架
• 内置 Web 管理面板：扫码登录、配置管理、接口调试一站式完成
• 双运行模式：Framework（QQ 进程内加载）与 Shell（独立进程）
• 离线自愈：被踢下线或静默离线后自动重启并快速登录

🛠️ 环境准备与 5 分钟快速启动

前置条件清单：

• Node.js ≥ 18（engines 字段硬性要求）
• pnpm 包管理器（推荐最新稳定版）
• 开发调试模式需要 Windows 系统 + 已安装的 NTQQ 桌面客户端

最简安装启动：

git clone https://gitcode.com/gh_mirrors/na/NapCatQQ
cd NapCatQQ
pnpm install
pnpm run build:shell

构建完成后执行 pnpm run dev:shell 即可启动开发调试流程。

最容易踩的坑：dev:shell 底层会调用 PowerShell 脚本 nodeTest.ps1，它从 Windows 注册表读取 QQ 安装路径，所以只能在装有 NTQQ 的 Windows 机器上跑。另外 Windows Server 默认不带「媒体基础」组件（缺 mfplat.dll），加载 wrapper 时会直接报错，需先在服务器管理器中勾选安装。

🧩 核心概念：monorepo 架构一图看懂

packages/
├── napcat-core/          # 核心层：NTQQ API 封装、协议包处理、事件监听
├── napcat-framework/     # 框架模式：在 QQ 进程内加载 NapCat 的入口
├── napcat-shell/         # Shell 模式：独立进程入口（构建产物供 QQ 加载）
├── napcat-onebot/        # OneBot 11：action 路由、事件模型、网络适配器
├── napcat-webui-backend/ # Web 管理面板后端（登录鉴权、配置、终端）
├── napcat-webui-frontend/# WebUI 前端（React + Vite）
├── napcat-protocol/      # NapCat 原生协议
├── napcat-common/        # 通用工具：路径、日志、HTTP、文件处理
└── napcat-develop/       # 开发工具：QQ 路径探测、启动脚本

各模块一句话说明：

• napcat-core：所有 QQ 能力的底座。apis/ 下按域拆分（msg、group、friend、file、flash、database 等），listeners/ 监听内核事件，packet/ 处理底层协议包
• napcat-onebot：把 core 的能力翻译成 OneBot 11 标准接口，action/ 按 group、msg、user、file、system 分类组织
• napcat-webui-*：提供扫码登录、网络配置、日志查看、OneBot 调试等网页操作能力
• napcat-common / napcat-types：跨模块共享的路径封装、日志与类型定义

🚀 实操：跑通第一个 OneBot 11 接口

Step 1 构建 Shell 模块

执行 pnpm run build:shell。它是 QQ 进程实际加载的产物，后续开发都要基于它。

Step 2 启动开发流程

执行 pnpm run dev:shell。脚本会自动探测 NTQQ 路径、注入 Shell 产物并拉起服务。此时 NapCat 会在运行目录生成 config/、logs/ 等目录。

Step 3 打开 WebUI 管理面板

浏览器访问 http://127.0.0.1:6099/webui/?token=<你的token>。token 在 config/webui.json 中（默认值 random，启动时可自动随机化）。

Step 4 登录 QQ 账号

在 WebUI 页面扫码登录，或选择历史账号走快速登录。WebUI 会实时展示登录阶段：等待扫码 → 已扫描 → 就绪。

Step 5 验证 OneBot 接口

配置模板 onebot11.json 默认启用了 HTTP（3000 端口）与 WebSocket（3001 端口）两条通道。登录成功后，用任意 HTTP 客户端请求 /get_login_info：

curl http://127.0.0.1:3000/get_login_info

返回当前账号的 user_id、nickname，说明机器人已经完整跑通「协议端 → OneBot 接口」全链路。

⚙️ 配置体系速查：三个关键 JSON

NapCat 的配置分层清晰：核心运行配置（napcat.json）、OneBot 网络配置（onebot11.json）、WebUI 安全配置（webui.json），均位于运行目录的 config/ 下。仓库内的模板可作参考：napcat.json、onebot11.json、webui.json。

文件	职责	高频调整项
napcat.json	核心运行行为	fileLog、consoleLogLevel、packetBackend、o3HookMode、bypass
onebot11.json	OneBot 11 网络适配器	httpServers.port（默认 3000）、websocketServers.port（默认 3001）、token
webui.json	Web 管理面板	port（默认 6099）、token、ipWhitelist、accessControlMode

几个值得注意的行为：

• 运行时写入路径（config/logs/cache/plugins）由 NapCatPathWrapper 统一管理，可用环境变量 NAPCAT_WORKDIR 覆盖
• OneBot 每个网络通道都支持独立的 token 鉴权与 messagePostFormat（array/object），多实例接入不同机器人框架时互不干扰
• WebUI 支持 IP 黑白名单与 2FA，公网暴露时建议开启

🎯 典型应用场景

场景一：智能客服机器人

• 用户痛点：重复问题占用人工，夜间无人应答
• 项目怎么解：订阅 OneBot 消息事件，按关键词路由到自动回复逻辑，send_msg 类动作即时响应；复杂问题转人工并记录上下文
• 最终效果：常见问题秒回，人工只处理长尾问题，7×24 不间断服务

场景二：社群管理助手

• 用户痛点：入群审核、违规处理、公告维护全靠手动
• 项目怎么解：监听 group_request 等事件自动审批，set_group_ban、set_group_kick 等群管动作执行处罚，send_group_notice 定时发布公告
• 最终效果：群规自动执行，管理员从重复劳动中解放

场景三：消息中转与工具集成

• 用户痛点：QQ 与其他平台信息割裂，文件传递麻烦
• 项目怎么解：利用 WebSocket 通道把 QQ 消息桥接到自有服务；文件类 action（群文件、在线文件、闪传）覆盖大文件收发
• 最终效果：QQ 变成统一的消息入口，其他平台通过 OneBot 协议无缝接入

🩹 高频问题与排错

问题一：wrapper 加载失败，提示找不到模块

• 现象：启动时报 The specified module could not be found
• 根因：Windows Server 默认缺少「媒体基础」组件（mfplat.dll）
• 解决：服务器管理器「添加角色和功能」勾选「媒体基础」，或管理员 PowerShell 执行 Install-WindowsFeature Server-Media-Foundation 后重启

问题二：dev:shell 启动即报错

• 现象：脚本找不到 QQ 路径或 versions 目录为空
• 根因：未安装 NTQQ，或注册表中的卸载信息缺失
• 解决：确认 NTQQ 已正常安装并可登录；若 versions/ 下有多个版本目录，脚本会自动选最新修改时间的那个，属正常行为

问题三：WebUI 打不开或提示 token 错误

• 现象：浏览器访问 6099 端口被拒或登录失败
• 根因：URL 未带 token，或 token 已被随机化
• 解决：查看 config/webui.json 中的 token 值拼入 URL；若开了 accessControlMode，确认本机 IP 在 ipWhitelist 内

问题四：端口冲突

• 现象：OneBot HTTP/WebSocket 或 WebUI 启动失败
• 根因：3000、3001、6099 端口被占用
• 解决：netstat -ano | findstr 3000 定位占用进程，或修改对应 JSON 中的 port 字段后重启

问题五：账号频繁掉线

• 现象：机器人间歇性无响应
• 根因：服务端踢下线或会话静默失效
• 解决：不必手动处理——离线恢复链路（offline-recovery.ts）会自动重启 Worker 并走快速登录，WebUI 状态栏会显示 reconnecting → ready 的全过程

📚 延伸资源与下一步

• 项目总览与社区入口：README.md（文档站点、QQ 群、Telegram 链接均汇总在此）
• 核心协议层源码：packages/napcat-core/
• OneBot 11 动作实现：packages/napcat-onebot/action/
• WebUI 后端 API：packages/napcat-webui-backend/src/api/
• 自动化测试用例：packages/napcat-test/

接下来你可以做的三件事：

1. 用 WebUI 的 OneBot 调试入口逐个试跑 get_status、get_login_info，熟悉标准动作的入参与返回
2. 接入一个 OneBot 11 客户端框架，写一个「@机器人即回复」的最小 Demo
3. 跑一遍 pnpm run test，通过测试用例理解各模块的行为边界

现在打开终端，把 pnpm install 敲下去吧——十分钟后你手里会有一个能收发消息的 QQ 机器人。最后提醒一句：请遵守平台规则与当地法律法规，合理使用机器人功能。

【免费下载链接】NapCatQQ Modern protocol-side framework based on NTQQ 项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ