NapCat QQ Client

基于 Electron + React + TypeScript 的桌面端 QQ 风格客户端，用于连接 NapCat（OneBot v11）服务，实现私聊/群聊消息收发、会话管理与托盘通知。

功能说明

1）聊天与会话

• 支持私聊、群聊消息实时收发。
• 会话列表按最新消息时间排序，并显示未读计数。
• 支持加载本地历史消息（IndexedDB 持久化）。
• 支持引用回复、复制消息、图片预览。
• 支持 Emoji、图片、文件发送。
• 群聊支持 @ 成员。

2）通知与托盘

• 支持系统通知与托盘未读提醒。
• 会话级通知开关（默认关闭，可在会话右键菜单开启）。
• 托盘可展示未读预览并聚合显示。
• 点击通知或托盘预览可跳转到对应会话（区分群聊/私聊）。

3）界面与设置

• 主题切换：浅色 / 深色 / 跟随系统。
• 全局字体大小可调。
• 发送快捷键：Enter 或 Ctrl + Enter。
• 新消息提示音开关。
• 关闭按钮行为可选：最小化到托盘 / 直接退出。

技术栈

• Electron 40
• React 19
• TypeScript 5
• Vite 7
• Tailwind CSS 3
• Zustand
• Dexie（IndexedDB）

环境要求

• Node.js（建议 20+）
• npm（随 Node.js 安装）
• Windows 10/11（打包目标为 Windows）

安装与开发

1. 安装依赖

npm install

2. 启动开发环境

npm run dev

该命令会并行启动：

• 前端开发服务器（Vite，默认 http://localhost:5173）
• Electron 主进程

3. 首次使用配置

启动后进入「设置 -> 通用/连接」，配置：

• NapCat WebSocket URL（示例：ws://127.0.0.1:3000）
• Access Token（可选）

保存后点击连接即可。

打包 Windows EXE

执行：

npm run build

打包产物默认输出到：

• release_v2/MyQQ-Setup-<version>.exe（安装包）
• release_v2/win-unpacked/（免安装目录）

说明：

• 构建流程会先编译主进程 TypeScript，再构建前端并调用 electron-builder。
• 如在 Windows 下遇到权限相关错误，请尝试使用管理员权限终端执行。

常用命令

命令	说明
npm run dev	启动完整开发环境（前端 + Electron）
npm run dev:frontend	仅启动前端（Vite）
npm run dev:backend	等待前端后启动 Electron 主进程
npm run build	打包 Windows 安装包与目录产物
npm run preview	预览前端构建结果

项目结构

src/
  main/                # Electron 主进程与 preload
  renderer/            # React 渲染进程
    src/
      components/      # UI 组件
      hooks/           # 自定义 Hook（主题、通知）
      services/        # OneBot 通信与消息处理
      store/           # Zustand 状态管理
      utils/           # 工具函数（如 QQ 表情映射）

常见问题（FAQ）

1）无法连接 NapCat，状态始终是“未连接”

请检查：

1. NapCat 服务是否已启动。
2. WebSocket 地址是否正确（协议、IP、端口）。
3. 是否需要 Access Token，以及 Token 是否填写正确。
4. 本机防火墙是否拦截了对应端口。

2）通知没有弹出或没有声音

请检查：

1. 该会话是否已开启通知（会话列表右键）。
2. 系统通知权限是否允许该应用。
3. 设置中的“新消息提示音”是否已开启。

3）关闭窗口后程序没有退出

这是预期行为：当“关闭按钮行为”设置为“最小化到托盘”时，点击关闭只会隐藏到托盘。可在设置中改为“直接退出程序”。

4）消息里出现 [动画表情] 或 [表情] 文案

这是对部分消息段（如 mface）的兼容展示兜底，避免出现异常占位符（如 [[动画表情]]、[表情:]）。

5）打包后在哪里找安装包

默认在 release_v2/ 目录下，文件名类似：MyQQ-Setup-1.0.0.exe。

相关文档

• PRD.md
• ARCHITECTURE.md

许可证

ISC