+3
日增长
1,384
stars
113
forks
6
watchers
196
prs
227
issues
38
releases
README
// 小广告 //
想在终端连接 Napcat?来看看 Stapxs QQ Shell 吧!
---
Stapxs QQ Lite
一个兼容 OneBot 的非官方网页 QQ 客户端
🌎 访问 DEMO |
📦️ 下载程序 |
💬 反馈问题
本网页应用仅供学习交流使用,请勿用于其他用途
版权争议请提出 issue 协商
!view
☕️ 赞助项目
https://www.ifdian.net/a/stapxs
社区版本
以下是一些社区支持的版本,非常推荐大家试用:
- Stapxs QQ Lite X:扩展了更多功能的社区版本,支持更多接近原版 QQ 的功能
- Stapxs QQ Lite Pre Preview:Stapxs QQ Lite 的预览版本,跟随 dev 分支更新,可体验最新功能
✨ 特性支持
- ✅ 使用 Vue.js 全家桶开发,快乐前后端分离
- 🎨 自适应布局,竖版也能使用
- 🖥️ 支持 PWA(都有 Electron 了(小声))
- 🌚 Light/Dark Mode 自动切换
- 🍱 该有的都有(虽然比不过官方端)
- 复杂消息显示、转发、回复、撤回
- 群文件、群公告、群设置(一小部分)、精华消息
- 图片、收藏表情、文件发送
- 📦️ 支持多种 bot,我就是要用!
- 🔥 水深火热但是更好看的 Electron 客户端
- 🥚 彩蛋!来更多的彩蛋!
- 🛠 更多特性开发中
♿️ 快速使用
运行服务
Stapxs QQ Lite 需要一个 QQ Bot 后端提供服务。由于 QQ Bot 的部署较为复杂,请移步 Bot 适配情况 issue 查看目前支持的 Bot 并选择一个查阅其部署文档。
访问网页
本仓库开启了 GitHub Pages,所有向主分支提交的代码将会自动构建并发布。你可以直接访问 🌎 这个页面 来使用已构建并部署的在线版本。
安装客户端
除了直接使用本仓库的构建页面,你也可以下载使用 Electron 打包的功能稍稍更丰富的客户端版本,访问 📦️ 这里 查看版本发布列表。
你也可以使用包管理器来安装,这样可以更方便地更新 Stapxs QQ Lite 而无需每次都从 GitHub 手动下载,访问 💬 这里 查看目前支持的包管理器。
在 Napcat 中安装
Stapxs QQ Lite 也可以作为 Napcat 的插件运行,点击下面的快速安装按钮在 Napcat 插件商店中安装:
自行部署网页
Stapxs QQ Lite 在版本发布时会构建 Web 文件,你可以在 📦️ 这里 找到它,通常命名为 Stapxs.QQ.Lite--web.zip,下载后解压并放置到你的网页服务器中即可。
不会部署网页服务器?Stapxs QQ Lite 网页版已经发布到了 npm!你可以使用 npx 工具快速启动:
bash
npx ssqq-web hostname=127.0.0.1 port=8081
使用 Docker 部署网页
Stapxs QQ Lite 已经原生支持了 Docker 部署,使用命令
bash
docker pull ghcr.io/stapxs/stapxs-qq-lite-2.0:latest
来拉取最新的镜像,如果您无法使用或者GHCR速度很慢,可以使用命令
bash
docker pull ghcr.nju.edu.cn/stapxs/stapxs-qq-lite-2.0:latest
来从镜像站拉取镜像,使用时请将容器内的8080端口对外开放,80端口可以忽略。
💬 提醒和问题
以下是关于使用 QQ Bot 和第三方客户端的常见疑问,你也可以查看 常见问题 issue 获取更多使用和部署相关的问题解答。
我能使用其他 QQ HTTP Bot 吗
- 如果它兼容 OneBot 11 协议,你可以尝试连接,但由于消息体格式和接口扩展的差异,大部分情况下可能无法完全正常使用。
已兼容的 Bot 列表可以在 这里 查看。
使用 Bot 是否有风险
- 使用 QQ Bot 服务可能存在一定风险,此风险并非由 Stapxs QQ Lite 造成,而是使用 QQ Bot 服务本身的风险。请自行查阅你所使用的 QQ Bot 相关文档以了解风险信息。
我遇到了问题
- 如果遇到任何问题,欢迎发起 issue 询问!发现 BUG 或有优化建议也欢迎反馈。
📦️ 构建应用
为了规范对其他仓库的引用,Stapxs QQ Lite 仓库包含一些 Git 子模块,这意味着你需要在克隆仓库时包含子模块:
bash
git clone https://github.com/Stapxs/Stapxs-QQ-Lite-2.0.git --recursive
如果你已经克隆了仓库,可以使用以下命令补全子模块:
bash
git submodule update --init
在开始构建之前,请先安装依赖。请确保已安装 yarn:
bash
安装依赖
yarn install
另外,Stapxs QQ Lite 使用了高德地图 API 来显示位置共享地图。.env 文件中提供了一个默认的高德地图 API Key,如果你打算自行部署,建议在 这里 申请属于你自己的 API Key 并替换默认值。
我们强烈建议使用自己的 API Key,因为默认 Key 有使用次数限制。
构建 Web 页面
Stapxs QQ Lite 是一个基于 Vue 的单页应用,如果你想自行部署到网页服务器需要进行构建。你也可以直接前往 这里 下载预构建好的文件包。
以下是构建该项目的命令,构建结果将输出在 dist 目录下:
bash
运行本地调试
yarn dev
代码检查和自动格式化
yarn lint
构建应用
yarn build
SSE 模式
Stapxs QQ Lite 支持 SSE 模式。在此模式下,应用将以 HTTP SSE + HTTP API 的方式连接到 QQ Bot 后端,提供更快速和轻量化的连接;甚至可以直接禁用 SSE 通知推送,仅使用 HTTP API 进行通信。
SSE 模式不支持动态切换,需要在构建前修改 .env 环境变量中 VITE_APP_SSE 开头的配置项来启用。启用 SSE 模式后,页面将无法使用其他连接模式。
~~~ ini
VITE_APP_SSE_MODE=true
VITE_APP_SSE_SUPPORT=true
VITE_APP_SSE_EVENT_ADDRESS=api/_events
VITE_APP_SSE_HTTP_ADDRESS=api
~~~
SSE_Top issues
#76[ 提醒 ] Bot 框架连接提醒和适配情况12 comments · 2023-11-14#373Windows客户端窗口拖动动画异常5 comments · 2026-05-25#413双击消息以回复3 comments · 2026-10-16#423群多了会很卡...2 comments · 2026-10-28#388窗口拖动异常卡顿延迟2 comments · 2026-06-17#421[Bug] 网页端中,系统通知不会自动消失1 comments · 2026-10-28#419UI对比度异常1 comments · 2026-10-25#408群中(大量)撤回消息后获取不到历史消息1 comments · 2026-09-26
Latest release
v3.5.2 v3.5.2 2026-10-13Release 累累 更新内容 ✨ 增加对频道分享卡片的支持 ✨ 现在支持自动跳转加载未加载的回复消息了 <- @AlexbeatsZ 🐛 https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/issues/407 修复在 Wayland 下 AppImage 无法启动的问题 :bug: https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/issues/370 修复在 iOS 端由网络扫描功能导致的 OOM 闪退问题 :bug: 修复赞助者列表加载失败导致的设置页加载异常 :bug: 修复历史记录在切换时可能出现的加载混杂的问题 <- @AlexbeatsZ 🐛 https://github.com/Stapxs/Stapxs-QQ-Lite-2.0/issues/371 修复合并转发发消息在 LLOneBot 中无法查看的问题 <- @AlexbeatsZ ⬆️ 更新项目至 ts6,为 ts7 做好准备 自动构建信息 - 构建时间:2026-10-13T16:31:39+08:00 - 构建提交:0afd7f1ff1dee7933a1e344cce4700e05cd096d6 - 构建分支:c472422f50d27ef921280c84cbe5f7dbf6eb031b