企业官网建设流程全解析

如何用NapCatQQ搭建QQ机器人：从安装NTQQ到发出第一条OneBot 11消息

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

想让 QQ 自动回复群消息、定时推送通知，官方 QQ 并不开放这类能力，而 go-cqhttp 等传统协议端项目大多停止维护，新手自己搭经常卡在登录阶段。NapCatQQ 是一套基于 NTQQ 客户端实现的 QQ 机器人协议端，它直接挂在你机器上已安装的 QQ 进程里，对外暴露完整的 OneBot 11 API：接收群/私聊消息、主动发消息、管理文件与群成员。

项目速览：NapCatQQ 能做什么

上手：第一次跑通 NapCatQQ

第 1 步：准备环境。Node.js ≥ 18（各 package 的 engines 声明）、pnpm；主平台是 Windows，需要先装好 QQNT（NTQQ 版 QQ）。为什么这么做：启动器通过系统注册表定位 QQ 安装路径并注入 hook，机器上必须有一个真实的 QQ 客户端。

第 2 步：拉代码装依赖。

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

第 3 步：拿构建产物。两条路：

• 首次使用建议直接去项目 Release 页下载最新版，解压后双击launcher.bat（README 对首次使用者的建议）；
• 或源码构建：在根目录依次执行build:shell、build:framework、build:webui、build:plugin-builtin（见根package.jsonscripts），配置模板在packages/napcat-develop/config/下。

为什么区分这两条路：源码构建步骤多且依赖各包版本一致，官方包对新手更稳；源码构建留给二次开发。

第 4 步：扫码登录。启动后浏览器访问http://127.0.0.1:6099（token 见"避坑"一节），在 WebUI 里扫码登录 QQ。为什么这么做：WebUI 是整个实例的管理入口，网络配置、日志、插件管理都在这里。

第 5 步：验证 OneBot 11 通路。开发配置默认启用 HTTP 服务（端口 3000），发一条私聊消息测试：

curl -X POST http://127.0.0.1:3000/send_private_msg \ -H 'Content-Type: application/json' \ -d '{"user_id": 123456, "message": "hello"}'

收到消息即表示协议端、网络层、发送链路全部打通。实际端口与开关以onebot11.json为准。

场景拆解：OneBot 11 协议端的四种典型用法

收群消息做自动回复：WebSocket 事件推送

onebot11.json的network字段提供 6 类通道：httpServers、httpSseServers、httpClients、websocketServers、websocketClients、plugins，各通道可独立开关、配端口/token。做自动回复推荐让事件主动推给上游：开启websocket-server（开发配置默认 3001 端口），你的监听服务连接ws://127.0.0.1:3001即可收到群消息、私聊、好友/加群申请等事件。事件结构按 message、notice、request、meta 四类组织在napcat-onebot/event/目录下，接上游前先看这里。

主动发消息与文件管理：OneBot 11 接口有哪些

接口按类别组织在 packages/napcat-onebot/action/：群（group/，含禁言、踢人、公告、群文件）、用户（user/）、消息（msg/）、文件（file/，下载/上传/在线文件）、系统（system/），另有一批 go-cqhttp 兼容接口（go-cqhttp/，如UploadGroupFile、GetGroupMsgHistory）。需要某个"应该有"的接口时，先搜这个目录确认是否已实现，比翻文档快。

WebUI 登录与远程管理

WebUI 默认监听 6099 端口、token 鉴权，支持 IP 白/黑名单、登录限频（loginRate）；在配置目录放cert.pem/key.pem会自动启用 HTTPS。源码在 packages/napcat-webui-backend/，路由文件（登录、配置、插件、更新）都在src/router/下，想知道 WebUI 每个按钮背后调什么接口，看这里最直接。

加载插件扩展能力

插件管理器扫描插件目录并按"官方插件 ID 白名单"加载（目前为 napcat-plugin-builtin、napcat-plugin-cleaner、napcat-plugin-ssqq、napcat-plugin-qce），源码还带敏感词检测。插件可注册 OneBot 接口与自定义路由，加载与类型定义见napcat-onebot/network/plugin/目录。

避坑与进阶：新手常见卡点与源码入口

四个常见坑

• WebUI 401 / 没有 token。原因：token 为默认值时，启动会自动生成随机 token，并在 QQ 登录成功后通过私聊消息发送给你。处理：用 QQ 收到的 token 访问；部署环境可预设环境变量NAPCAT_WEBUI_SECRET_KEY。
• QQ 被踢下线/静默离线后实例自己"活了"。原因：内置离线恢复逻辑——被踢（KickedOffLine）约 3.5 秒后自动重启 worker 重登；静默离线（SelfOffline）会先等 60 秒看 QQ 能否自行重连，避免网络抖动导致误重启；另有 10 秒内多次崩溃的进程保护。处理：多数情况无需人工干预，留意 WebUI 日志即可。
• 启动提示找不到 QQ 安装。原因：启动器从注册表读 QQ 路径，装的不是 QQNT 版本、或以普通权限运行都会失败。处理：确认安装 QQNT 客户端，并以管理员身份运行启动器。
• 服务不在预期端口。原因：端口被占用时 WebUI 会自动尝试其他候选端口（上限 100 次）。处理：以启动日志打印的实际监听端口为准，别写死 6099。

进阶：深入源码从哪读

• 想理解协议端底层：看 packages/napcat-core/，其中packet/目录含协议包处理与 transformer（proto 结构定义），listeners/是 QQ 内核事件的监听入口。
• 想写自己的插件或扩展 OneBot 接口：读napcat-onebot/network/plugin/的 loader 与 types，再对照napcat-onebot/action/example/下的示例代码。

收尾：现在你能做出什么

回到开头的场景：群消息自动回复已经通了——上游服务连 3001 的 WebSocket 收事件，用 OneBot 11 action 回消息，文件和群成员管理也有现成接口；需要接上游 bot 框架（如 README 推荐的 AstrBot）时，从 websocket-client / websocket-server 配置入手即可。下一步动作：按顺序通读packages/napcat-onebot/action/example/的接口示例，然后在 WebUI 里逐个验证 action，把常用接口的参数摸熟；具体行为细节以项目最新文档为准。

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