NapCatQQ 快速上手：从克隆到跑通的完整路线

NapCatQQ 快速上手：从克隆到跑通的完整路线

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

NapCatQQ 是一个基于 NTQQ 协议的机器人框架，协议层的收发、登录、群管理由框架负责，你的业务逻辑则通过它暴露的 OneBot 标准接口来写。如果你的目标是在它上面部署一个能用的 QQ 机器人，或者要改它的源码，按下面这条路线走完，你能完成三件事：确认环境要求、装好依赖、让构建和开发服务器第一次跑起来。

跑通之前，先确认这三件事

下面三条都是仓库里的硬约束，不是建议。README 同时自述可以在低内存系统上长时运行，如果你的机器资源紧张，这点值得先记下来。

• Node.js >= 18.0.0：每个子包的package.json都在 engines 里写死了"node": ">=18.0.0"，低于这个版本，项目依赖的部分语法和特性无法正常工作。
• pnpm：根目录的 pnpm-workspace.yaml 声明了packages/*，包之间的依赖全部用workspace:*协议书写（napcat-framework 对 napcat-core 的依赖就是这种写法）。只有 pnpm 能解析这种协议，一次安装就能把整张依赖图铺平，避免包之间版本漂移。
• TypeScript 环境：整个项目用 TS 编写，基础编译选项strict、bundler模块解析、ES2021target 统一由tsconfig.base.json给出，你的编辑器与终端工具链需要能正常处理 TypeScript。

另外在 Windows 上还需要一个兼容的 QQ 客户端（NTQQ）。它是协议层的运行时依赖，不影响构建本身，但登录机器人时必须有。

📥 克隆仓库并安装依赖

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

安装过程中 pnpm 会连带处理各子包的依赖并链接 workspace 内部引用，完成后packages/下应能看到 napcat-core、napcat-onebot 等全部模块。

装不上时按顺序查三处：

1. 网络到 npm registry 是否可达，换成国内镜像源通常能解决大部分下载超时。
2. pnpm 版本过旧导致不识别 workspace 协议，升级到最新版再试。
3. 缓存损坏，执行pnpm store prune清理 store 后重装。

🏗️ 第一次构建：shell 和 framework 谁先谁后

构建命令集中在根目录package.json的 scripts 里，本质都是pnpm --filter <包名>指向某个子包：

pnpm run build:shell pnpm run build:framework

先 shell 再 framework，顺序的原因在于 shell 入口（napcat-shell）是框架层构建所依赖的产物；仓库里的build:shell:config变体也印证了这一点，它先构建 napcat-shell，再把 napcat-develop 的 config 目录复制到napcat-shell/dist/config。

想更快看到反馈可以跑pnpm run dev:shell启动开发服务器，它内部启动的是 napcat-develop 包，在 Windows 上实际执行powershell ./nodeTest.ps1，所以这条入口基本只覆盖 Windows 环境。首次运行推荐用它，因为边跑边调比反复整包构建省时间。

构建通过后，用pnpm run test跑 napcat-test 包的 vitest 用例做基线验证。构建无报错加上测试通过，是判断环境可用的最低标准。

跑起来之后，配置改在哪一层

配置分三层，各自管不同的事：

• 根层（package.json 的 scripts）：只定义有哪些命令、按什么顺序执行，不放任何业务配置。
• 编译层（tsconfig.base.json 加各子包自己的tsconfig.json）：paths别名把模块名直接映射到源码目录，比如napcat-core指向./packages/napcat-core/index.ts。你要新增跨包依赖时，先动这里的别名。
• 运行时层：各子包自己的配置文件。OneBot 的协议参数和网络模式由 napcat-onebot 管理，HTTP Server、SSE、WebSocket 客户端/服务端这几种连接方式都在它的network/目录下。

按任务决定动哪个模块，比按目录逐个看更快：

• 改机器人的 API 行为（消息收发、好友与群管理、文件传输）：动 napcat-core，apis/、services/、listeners/各自承接一块。
• 接入你现有的开发框架：动 packages/napcat-onebot/，它是 OneBot 标准接口层，接框架时通常不用碰协议层。
• 改管理界面：动 napcat-webui-frontend（React 应用）和后端 napcat-webui-backend，后者提供终端、OneBot 相关 API。

🔍 服务起不来时，按这个顺序排查

开发服务器或机器人进程起不来时，从外到内查：

1. 端口：先确认端口是否被其他进程占用，这是最常见的原因。
2. 环境变量：你以为设置过的变量在当前 shell 里是否真的生效、取值是否正确。
3. 版本兼容：Node 版本是否满足 engines 下限，子包之间的依赖版本是否一致。
4. 日志：Web UI（napcat-webui-frontend）带日志页面；打不开 UI 就先看终端输出，定位到是哪个包的脚本失败。

构建本身报错时回到编译层：核对tsconfig.base.json的选项和你改过的地方是否冲突，以及跨包依赖链是否完整。

接下来做什么

1. 跑一遍pnpm run build:shell和pnpm run test，确认构建与测试基线通过。
2. 在 Web UI 打开 OneBot 网络配置，接一路 HTTP 或 WebSocket 连接，验证事件能从协议层流到你的客户端。
3. 需要改某个模块时，先定位它属于哪个包，再打开该包的vite.config.ts与tsconfig.json看它的构建和编译方式。

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