企业官网建设流程全解析

简介：这是一套基于ThinkPHP6与Swoole构建后端、UniApp开发前端并整体仿QQ的即时通讯项目源码工程，面向具备一定PHP与前端基础、希望深入理解即时通讯架构的开发者，可用于毕业设计、课程设计、大作业、工程实训及大创竞赛等场景，也适合作为学习练手或二次开发的起点。资源包共约2000个文件，压缩后约89.04MB，以1491个js脚本、111个vue组件、91个json配置、302个md说明文档为主，另含少量css、txt与doc文件，覆盖前后端源码、工程配置与使用说明，结构完整便于按模块查阅。目前已有37人学习关注。项目代码经过测试运行，功能可用，可实现复现复刻；读者可借鉴其即时通讯核心逻辑、Swoole长连接处理与UniApp跨端界面实现，并在此基础上扩展新功能，设计报告亦可参考，遇到问题可联系作者获取解答与相关学习资料。

1. 从零搭一套仿 QQ 的即时通讯：ThinkPHP6 + Swoole + uni-app 到底能跑多远

很多人第一次听到「ThinkPHP6 + Swoole + uni-app 做仿 QQ 即时通讯」，第一反应是「这不就是个 CRUD 加个 WebSocket 吗」。真动手才知道，消息时序、离线补偿、多端同步、心跳保活、群聊扩散，每一项都能让一个没踩过坑的团队卡上两三个月。这个组合的价值在于：后端用 ThinkPHP6 做业务接口和后台管理，Swoole 扛长连接和消息推送，前端用 uni-app 一套代码覆盖 H5、微信小程序、Android、iOS 甚至鸿蒙，开发成本压得很低。它适合中小团队快速验证 IM 产品，也适合个人开发者拿来做技术纵深。但「能跑」和「能上线」之间隔着一条河，这篇就把这条河上的桥怎么搭、哪里会塌，一次讲清楚。

2. 后端选型：为什么是 ThinkPHP6 管业务、Swoole 管长连接

2.1 两者分工的边界在哪里

ThinkPHP6 本身是同步阻塞的 PHP 框架，一个请求一个进程，处理登录、注册、好友关系、群资料、历史消息拉取这类「短连接、有事务、要落库」的业务非常顺手。Swoole 则是常驻内存的异步并发扩展，它把 PHP 从「请求来了才启动」变成「进程一直活着等事件」，天生适合 WebSocket 长连接、消息广播、定时任务。

常见做法是让两者各管一摊：HTTP 接口走 ThinkPHP6 的 FPM 或 Swoole HTTP Server，WebSocket 连接走独立的 Swoole WebSocket Server。两者通过 Redis 的发布订阅或者内部 TCP 端口通信。不要让 ThinkPHP6 的控制器直接去操作 WebSocket 连接对象，那是典型的架构翻车点——FPM 进程和 Swoole 进程根本不在一个内存空间。

我一般会这样划分：

这个划分不是死规定，但边界清晰能省掉大量调试时间。新手最容易犯的错是把所有逻辑塞进 Swoole 的 onMessage 回调里，结果一个慢查询就把整个连接池堵死。

2.2 用 Swoole 启动 WebSocket 服务的最小命令

先确认环境：PHP 7.4 以上、Swoole 4.8 以上、Redis 扩展、PDO MySQL 扩展。ThinkPHP6 用 Composer 装，Swoole 用 pecl 装。

# 安装 ThinkPHP6 composer create-project topthink/think im-server cd im-server # 安装 Swoole（假设已装 pecl） pecl install swoole # 在 php.ini 中加入 extension=swoole.so # 安装 Redis 扩展 pecl install redis # 在 php.ini 中加入 extension=redis.so # 验证 php -m | grep -E "swoole|redis"

确认扩展加载后，在项目根目录建一个swoole_server.php，这是 WebSocket 服务的入口：

<?php // swoole_server.php use Swoole\WebSocket\Server; use Swoole\Http\Request; use Swoole\WebSocket\Frame; $server = new Server("0.0.0.0", 9502); // 连接建立时触发，用于绑定用户ID和fd $server->on('open', function (Server $server, Request $request) { // 实际项目中这里要校验 token，从 Redis 取用户信息 echo "connection open: {$request->fd}\n"; }); // 收到消息时触发，核心分发逻辑 $server->on('message', function (Server $server, Frame $frame) { $data = json_decode($frame->data, true); // 根据消息类型分发：单聊、群聊、心跳、已读回执 switch ($data['type'] ?? '') { case 'ping': $server->push($frame->fd, json_encode(['type' => 'pong'])); break; case 'single': // 单聊：查目标用户fd，推送 break; case 'group': // 群聊：查群成员fd列表，批量推送 break; } }); // 连接关闭时触发，清理在线状态 $server->on('close', function ($server, $fd) { echo "connection close: {$fd}\n"; }); $server->start();

这段代码的逻辑说明：open回调里做鉴权和 fd 与 uid 的绑定，通常把映射写进 Redis 的 Hash，key 是online:uid，value 是 fd。message回调是消息总线，按 type 字段分发。close回调必须清理 Redis 里的映射，否则会出现「用户已离线但系统以为在线」的幽灵状态。

参数说明：端口 9502 是 Swoole 常用端口，可改。0.0.0.0表示监听所有网卡，生产环境建议配合防火墙只开必要端口。json_decode的第二个参数 true 表示返回数组，方便后续处理。

启动命令：

php swoole_server.php

看到connection open日志就说明服务起来了。用浏览器控制台或者 WebSocket 测试工具连ws://127.0.0.1:9502就能验证。

2.3 消息时序和离线补偿怎么处理

即时通讯最怕的不是消息发不出去，而是消息顺序乱了、或者用户离线期间的消息丢了。Swoole 的 push 是异步的，多个消息同时推给同一个 fd 时，到达顺序不保证。解决办法是在服务端给每条消息分配一个自增序列号，客户端按序列号排序。

离线补偿的常见做法是：用户上线时，先拉取 Redis 里缓存的最近 N 条消息，再拉 MySQL 里的历史消息。Redis 用 List 结构，key 是msg:uid，每次推送前先LPUSH，用户上线后LRANGE取最近 100 条，取完DEL。这样既保证不丢，又不会让 Redis 无限膨胀。

// 用户上线时拉取离线消息 $redis = new Redis(); $redis->connect('127.0.0.1', 6379); $offlineKey = "msg:offline:{$uid}"; $messages = $redis->lRange($offlineKey, 0, -1); if (!empty($messages)) { foreach ($messages as $msg) { $server->push($fd, $msg); } $redis->del($offlineKey); // 拉取后删除，避免重复 }

注意：lRange取完后立刻del有风险，如果推送过程中连接断了，消息就丢了。更稳妥的做法是先标记已读再删除，或者用 Redis 的MULTI事务包住。这个细节后面避坑章节还会展开。

3. 前端 uni-app 对接：一套代码怎么同时喂饱 H5 和小程序

3.1 WebSocket 连接在 uni-app 里的正确打开方式

uni-app 提供了uni.connectSocket这个跨端 API，H5、小程序、App 都能用。但不同端的表现差异很大，尤其是微信小程序对 WebSocket 的限制比 H5 多得多。常见做法是封装一个 Socket 管理类，统一处理连接、重连、心跳、消息分发。

// utils/socket.js class SocketManager { constructor() { this.socket = null; this.isConnected = false; this.reconnectTimer = null; this.heartbeatTimer = null; this.listeners = {}; } connect(url, token) { this.socket = uni.connectSocket({ url: `${url}?token=${token}`, success: () => console.log('socket connect success'), fail: (err) => console.error('socket connect fail', err) }); this.socket.onOpen(() => { this.isConnected = true; this.startHeartbeat(); }); this.socket.onMessage((res) => { const data = JSON.parse(res.data); // 按消息类型分发给注册的监听器 if (this.listeners[data.type]) { this.listeners[data.type].forEach(fn => fn(data)); } }); this.socket.onClose(() => { this.isConnected = false; this.stopHeartbeat(); this.reconnect(url, token); }); this.socket.onError((err) => { console.error('socket error', err); this.socket.close(); }); } startHeartbeat() { this.heartbeatTimer = setInterval(() => { if (this.isConnected) { this.socket.send({ data: JSON.stringify({ type: 'ping' }) }); } }, 30000); // 30秒一次心跳 } stopHeartbeat() { if (this.heartbeatTimer) { clearInterval(this.heartbeatTimer); this.heartbeatTimer = null; } } reconnect(url, token) { if (this.reconnectTimer) return; this.reconnectTimer = setTimeout(() => { this.reconnectTimer = null; this.connect(url, token); }, 5000); // 5秒后重连 } on(type, callback) { if (!this.listeners[type]) this.listeners[type] = []; this.listeners[type].push(callback); } send(data) { if (this.isConnected) { this.socket.send({ data: JSON.stringify(data) }); } } } export default new SocketManager();

逻辑说明：connect方法建立连接并注册四个回调。onOpen里启动心跳，onMessage里按 type 分发，onClose里触发重连，onError里主动关闭触发重连。startHeartbeat每 30 秒发一次 ping，服务端回 pong，用来检测连接是否还活着。reconnect用 setTimeout 做延迟重连，避免频繁重试打爆服务端。

参数说明：心跳间隔 30 秒是经验值，微信小程序建议不低于 20 秒，否则容易被系统回收。重连延迟 5 秒也是经验值，太短会导致服务端压力大，太长用户体验差。uni.connectSocket的 url 参数在 H5 端是ws://或wss://，在小程序端必须是wss://且域名要在小程序后台配置。

3.2 多端适配的 manifest 配置和条件编译

uni-app 的manifest.json是打包配置的核心，不同端的差异都在这里。做即时通讯项目，有几个配置必须改：

{ "name": "im-app", "appid": "", "description": "仿QQ即时通讯", "versionName": "1.0.0", "versionCode": "100", "transformPx": false, "app-plus": { "usingComponents": true, "nvueStyleCompiler": "uni-app", "compilerVersion": 3, "splashscreen": { "alwaysShowBeforeRender": true, "waiting": true, "autoclose": true, "delay": 0 }, "modules": { "Push": {}, "VideoPlayer": {} }, "distribute": { "android": { "permissions": [ "<uses-permission android:name=\"android.permission.INTERNET\"/>", "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>" ] }, "ios": {}, "sdkConfigs": {} } }, "quickapp": {}, "mp-weixin": { "appid": "你的小程序appid", "setting": { "urlCheck": false, "es6": true, "postcss": true, "minified": true }, "usingComponents": true, "permission": { "scope.userLocation": { "desc": "用于发送位置消息" } }, "requiredPrivateInfos": ["getLocation"] }, "h5": { "title": "仿QQ即时通讯", "router": { "mode": "hash", "base": "./" }, "devServer": { "proxy": { "/api": { "target": "http://127.0.0.1:8000", "changeOrigin": true } } } } }

逻辑说明：app-plus里的modules按需引入推送和视频播放模块，不用的模块不要加，否则包体积会膨胀。mp-weixin里的urlCheck: false是开发阶段跳过域名校验，上线前必须改回 true 并在小程序后台配置合法域名。h5里的proxy解决开发阶段跨域，生产环境用 Nginx 反代。

参数说明：transformPx: false表示不使用 px 转 rpx，即时通讯界面通常用 rpx 做自适应，这个选项按项目习惯设。router.mode用 hash 是为了兼容静态部署，如果服务器支持 history 模式可以改成 history。

条件编译是 uni-app 处理多端差异的利器，比如 WebSocket 地址在不同端不一样：

// #ifdef H5 const WS_URL = 'ws://127.0.0.1:9502'; // #endif // #ifdef MP-WEIXIN const WS_URL = 'wss://your-domain.com/ws'; // #endif // #ifdef APP-PLUS const WS_URL = 'ws://your-server-ip:9502'; // #endif

注意：微信小程序的 WebSocket 必须用 wss，且域名要在小程序后台的「开发管理-开发设置-服务器域名」里配置。H5 端如果页面是 https，WebSocket 也必须用 wss，否则浏览器会拦截。App 端相对宽松，但生产环境也建议上 wss。

3.3 消息列表和聊天窗口的渲染性能

仿 QQ 的聊天窗口要处理大量消息气泡，如果直接用 v-for 渲染几百条消息，低端安卓机上会卡到怀疑人生。常见优化手段有三个：虚拟列表、消息分页、图片懒加载。

虚拟列表在 uni-app 里可以用scroll-view配合scroll-into-view实现，只渲染可视区域内的消息。消息分页是每次只加载最近 20 条，上拉加载更多。图片懒加载用image组件的lazy-load属性。

<template> <scroll-view scroll-y :scroll-into-view="lastMsgId" @scrolltoupper="loadMore" class="msg-list" > <view v-for="msg in visibleMessages" :key="msg.id" :id="'msg-' + msg.id"> <view :class="['bubble', msg.from === myUid ? 'self' : 'other']"> <image :src="msg.avatar" lazy-load mode="aspectFill" class="avatar" /> <text class="content">{{ msg.content }}</text> </view> </view> </scroll-view> </template> <script> export default { data() { return { messages: [], visibleMessages: [], lastMsgId: '', pageSize: 20 }; }, methods: { loadMore() { // 从历史消息里再取一页 const start = this.visibleMessages.length; const more = this.messages.slice(start, start + this.pageSize); this.visibleMessages = [...more, ...this.visibleMessages]; }, scrollToBottom() { if (this.messages.length) { this.lastMsgId = 'msg-' + this.messages[this.messages.length - 1].id; } } } }; </script>

逻辑说明：scroll-into-view绑定最后一条消息的 id，新消息到达时自动滚到底部。scrolltoupper触发加载更多历史消息。visibleMessages只保留当前渲染的消息，避免一次性渲染全部。

参数说明：pageSize设为 20 是平衡加载速度和内存占用的经验值。lazy-load在 H5 端支持有限，小程序和 App 端效果更好。mode="aspectFill"保证头像不变形。

4. 避坑与排查：那些让项目延期两周的细节

4.1 心跳包发了但服务端没收到

现象：客户端日志显示每 30 秒发一次 ping，但服务端onMessage回调里看不到 ping 消息，连接过一段时间就被断开。

原因：微信小程序在后台运行时，WebSocket 会被系统挂起，setInterval也会被暂停。H5 端如果页面切到后台，浏览器会降低定时器频率。另外，Swoole 的onMessage回调里如果做了耗时操作，消息会排队，看起来像没收到。

解决：心跳间隔不要低于 20 秒，微信小程序建议 25 到 30 秒。服务端在onMessage里对 ping 做最快路径处理，不要查库。同时服务端要设置heartbeat_check_interval和heartbeat_idle_time，主动踢掉死连接。

$server->set([ 'heartbeat_check_interval' => 60, // 每60秒检查一次 'heartbeat_idle_time' => 120, // 120秒没数据就断开 ]);

4.2 离线消息重复推送

现象：用户上线后收到两条一样的离线消息，或者同一条消息在多个设备上重复出现。

原因：lRange取消息后del之前，如果推送过程中连接断了，消息没删掉，下次上线又拉一遍。或者多端登录时，每个端都去拉离线消息，导致重复。

解决：用 Redis 的MULTI事务包住lRange和del，或者用LPOP逐条取逐条删。多端场景下，离线消息只推给主设备，其他设备通过同步接口拉取。

$redis->multi(); $messages = $redis->lRange($offlineKey, 0, -1); $redis->del($offlineKey); $redis->exec();

4.3 群聊消息扩散导致服务端卡死

现象：一个 500 人群发消息，服务端 CPU 瞬间飙到 100%，其他用户的消息延迟好几秒。

原因：群聊消息要推给所有在线成员，如果在一个循环里同步push，每个 push 都有网络开销，500 个就是 500 次。而且如果某个成员的连接已经断了，push 会阻塞。

解决：用 Swoole 的Task异步任务处理群聊扩散，主进程只负责接收消息，扩散逻辑丢给 Task Worker。同时用push的返回值判断连接是否有效，无效的从在线列表里移除。

$server->on('message', function ($server, $frame) { $data = json_decode($frame->data, true); if ($data['type'] === 'group') { $server->task($data); // 丢给 Task Worker } }); $server->on('task', function ($server, $taskId, $workerId, $data) { $members = getGroupMembers($data['group_id']); foreach ($members as $uid) { $fd = getFdByUid($uid); if ($fd && !$server->push($fd, json_encode($data))) { removeOnline($uid); // push失败说明连接已断 } } return 'done'; });

4.4 uni-app 打包 H5 后 WebSocket 连不上

现象：开发环境 WebSocket 正常，打包部署到服务器后连不上，控制台报WebSocket connection failed。

原因：H5 打包后是静态文件，WebSocket 地址写的是ws://127.0.0.1:9502，部署到服务器后这个地址指向的是用户本机，不是服务器。另外如果页面是 https，WebSocket 必须用 wss。

解决：用环境变量区分开发和生产，生产环境用wss://your-domain.com/ws，并在 Nginx 里配置 WebSocket 反代。

location /ws { proxy_pass http://127.0.0.1:9502; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_read_timeout 3600s; }

4.5 消息时间显示错乱

现象：聊天窗口里消息的时间顺序和实际发送顺序不一致，尤其是快速连续发送时。

原因：客户端用本地时间排序，不同设备时间不同步。或者服务端没有给消息分配全局序列号，客户端按到达顺序渲染。

解决：服务端给每条消息分配自增序列号，客户端按序列号排序。时间显示用服务端时间，不要用客户端本地时间。

// 客户端按 seq 排序 messages.sort((a, b) => a.seq - b.seq);

5. 进阶技巧：用 Redis 发布订阅打通 ThinkPHP6 和 Swoole

5.1 为什么需要发布订阅

ThinkPHP6 处理完业务逻辑后，比如「用户 A 给用户 B 发了一条消息」，需要通知 Swoole 去推送。但 ThinkPHP6 是 FPM 进程，Swoole 是常驻进程，两者不能直接调用。常见做法是用 Redis 的发布订阅：ThinkPHP6 往频道里publish，Swoole 订阅这个频道，收到消息后推送给对应的 fd。

这个模式的好处是解耦：ThinkPHP6 不需要知道 Swoole 的地址和端口，Swoole 也不需要知道业务逻辑。坏处是 Redis 如果挂了，消息会丢。生产环境建议用更可靠的消息队列，比如 RabbitMQ 或 Kafka，但 Redis 对于中小项目够用。

5.2 在 Swoole 里订阅 Redis 频道

Swoole 的onWorkerStart回调里可以启动一个 Redis 订阅协程，注意要用Swoole\Coroutine\Redis或者独立的进程，不要阻塞主进程。

$server->on('workerStart', function ($server, $workerId) { // 只在第一个 worker 里订阅，避免重复消费 if ($workerId === 0) { go(function () use ($server) { $redis = new Swoole\Coroutine\Redis(); $redis->connect('127.0.0.1', 6379); $redis->subscribe(['im_channel'], function ($redis, $channel, $message) use ($server) { $data = json_decode($message, true); $fd = getFdByUid($data['to_uid']); if ($fd) { $server->push($fd, json_encode($data)); } }); }); } });

逻辑说明：go创建一个协程，subscribe是阻塞的，所以必须放在协程里。$workerId === 0保证只有一个 worker 订阅，避免消息被重复消费。getFdByUid从 Redis 里查 fd 映射。

参数说明：im_channel是频道名，可以按业务拆成多个频道，比如im_single、im_group。Swoole\Coroutine\Redis需要 Swoole 4.0 以上，且编译时开启了协程 Redis 支持。

5.3 ThinkPHP6 侧发布消息

在 ThinkPHP6 的控制器或服务层里，处理完业务逻辑后往 Redis 频道发布消息：

// app/service/MessageService.php namespace app\service; use think\facade\Cache; class MessageService { public function send($fromUid, $toUid, $content) { // 1. 落库 $msgId = Db::name('messages')->insertGetId([ 'from_uid' => $fromUid, 'to_uid' => $toUid, 'content' => $content, 'create_time' => time(), ]); // 2. 发布到 Redis 频道 $redis = Cache::store('redis')->handler(); $redis->publish('im_channel', json_encode([ 'type' => 'single', 'msg_id' => $msgId, 'from_uid' => $fromUid, 'to_uid' => $toUid, 'content' => $content, 'seq' => $msgId, // 用消息ID做序列号 ])); return $msgId; } }

逻辑说明：先落库拿到消息 ID，再用消息 ID 做序列号，保证全局唯一且递增。然后发布到 Redis 频道，Swoole 订阅后推送给目标用户。如果目标用户不在线，Swoole 会把消息存到离线队列。

参数说明：Cache::store('redis')->handler()拿到的是原生 Redis 对象，才能用publish。seq用消息 ID 是最简单的方案，如果分库分表了就需要单独的序列号生成器。

5.4 验证整条链路是否打通

启动 Swoole 服务，再开一个终端用 Redis 客户端手动发布一条消息：

redis-cli publish im_channel '{"type":"single","to_uid":1,"content":"test"}'

如果 Swoole 日志里看到推送记录，说明订阅生效。再用两个浏览器标签分别登录两个账号，互相发消息，看是否能实时收到。最后测离线场景：关掉一个标签，另一个标签发消息，再打开关掉的标签，看是否能收到离线消息。

我自己的习惯是每次改完消息链路，先跑一遍「在线互发 → 离线补偿 → 多端同步」三个场景，确认无误再继续开发其他功能。这个习惯帮我省掉了无数次上线后才发现消息丢失的后悔药。希望帮到你。

本文还有配套的精品资源，点击获取