简介面向网页端即时聊天开发场景的 LayIM 与环信 WebIM 整合 Demo适合具备一定前端基础、希望快速搭建 PC 端聊天界面的开发者学习参考。案例将 LayIM 的会话列表、联系人面板与环信消息能力结合演示文字和表情发送流程联系人与用户数据暂用本地假数据替换成自己的接口即可接入业务环信部分也需换成个人 Key。压缩包共 190 个文件约 1.7MB主要由 gif、png 等界面与表情素材js 脚本、css 样式、html 页面及少量字体和配置文件组成便于直接运行和按模块查阅。已有 1530 人学习下载。通过这份 Demo读者可参考前端聊天窗口的页面组织、样式适配和消息模块调用方式并了解张三、李四两个测试账号的通讯限制图片、文件发送仍需替换对应接口后启用适合作为网页即时聊天功能原型的改造起点。1. 网页即时聊天 Demo 的落地价值先别急着接 SDK先看这 4 个分水岭很多人拿到一套 PC 端网页即时聊天 Demo第一反应是换掉 logo、改个主题色就上线。真到联调才发现登录态、会话排序、消息回显、断线重连才是决定能不能交付的分水岭。这份前端实现的价值不在“有输入框和消息气泡”而在把聊天 UI、会话状态和即时通讯云适配层拆开让新手能跑通首条消息熟手能替换服务端实现。适合要做后台客服、内部协作、订单沟通页的团队也适合想拆聊天交互细节的前端。2. 拆开这套 PC 端 WebIMUI 层、会话层与适配层怎么解耦PC 端网页即时聊天看起来只是“左边会话列表、右边消息面板、底部输入框”但真正维护起来最容易出问题的是 SDK 调用散落在各个组件里。这套 Demo 的前端实现通常会把聊天主界面、会话列表、消息气泡、图片上传入口放在 UI 层把当前会话、消息缓存、未读数放在状态层再用一个适配文件包住即时通讯云 SDK。这样做的理由很实际UI 组件不关心消息从哪来适配层也不关心消息气泡长什么样后面换云服务、加本地缓存、做多标签页同步都有地方下手。2.1 目录边界聊天页最怕把 SDK 调用散落在组件里先看资源里的入口页和聊天目录不要急着改样式。我一般会先找三类文件聊天页面入口、消息渲染组件、SDK 适配文件。如果发现sendMessage、login、onMessage这些调用直接写在按钮点击事件里说明这个 Demo 还停留在演示阶段落地前必须收口。比较稳的拆法是src/im/adapter.js只暴露连接、登录、发消息、拉历史、标记已读、事件订阅这几个方法页面组件只调用适配层。// src/im/adapter.js // 页面只依赖这个对象后续换即时通讯云服务时优先改这里 export class IMAdapter { constructor(options) { this.options options; // appId、userId、token、心跳、重连参数 this.connection null; // 长连接或 SDK 连接实例 this.handlers new Map(); // 事件名 - 回调数组 } on(event, handler) { const list this.handlers.get(event) || []; list.push(handler); this.handlers.set(event, list); return () this.off(event, handler); } off(event, handler) { const list this.handlers.get(event) || []; this.handlers.set(event, list.filter(fn fn ! handler)); } emit(event, payload) { (this.handlers.get(event) || []).forEach(fn fn(payload)); } async connect() { // 真实项目在这里调用云服务 SDK 的连接方法 this.connection await this.createConnection(this.options); this.connection.onMessage msg this.emit(message, msg); this.connection.onClose reason this.emit(close, reason); } async sendText({ conversationId, content }) { if (!this.connection) throw new Error(IM_NOT_CONNECTED); return this.connection.sendText({ conversationId, content }); } }代码里的options不要直接从组件里拼统一从环境变量和登录接口拿。handlers用 Map 存事件是为了避免页面切换后旧组件还挂着消息监听造成同一条消息渲染两次。connect里只做连接和事件转发不在这里写业务提示业务提示放页面层适配层保持薄。2.2 登录态与连接态两个状态机混用就会反复重连血泪经验是登录成功不等于长连接可用长连接断开也不等于要重新登录。很多 Demo 把isLogin和isConnected合成一个布尔值结果网络抖一下页面就跳回登录页或者反复拿旧 token 重连。前端更稳的做法是分开两个状态authStatus记录未登录、登录中、已登录、登录失效connStatus记录未连接、连接中、已连接、重连中、已断开。页面上的输入框禁用逻辑只看connStatus路由守卫只看authStatus。token 过期时适配层抛出明确错误码页面层再决定刷新 token 还是跳登录。重连不要用固定 1 秒无限重试常见做法是指数退避加最大次数比如 1.5 秒、3 秒、6 秒、12 秒超过 8 次后提示用户手动重试。这个策略不玄学但能避开大量“刚断线就疯狂重连”的无效请求。2.3 消息模型文本、图片、系统消息统一成可渲染结构聊天页最怕每种消息各写一套渲染分支。资源里的 Demo 如果只演示文本消息落地时一定要先补消息模型。文本、图片、文件、系统提示、订单卡片最终都应该收敛成{ id, serverId, conversationId, type, content, status, createdAt, senderId }。id用于本地临时消息serverId用于服务端回执后替换status至少要有sending、sent、failed三态。这样消息列表只认结构不认来源。// src/message/model.js // 统一消息结构渲染层只按 type 分支不直接读 SDK 原始字段 export function normalizeMessage(raw, currentUserId) { return { id: raw.localId || raw.id, serverId: raw.serverId || raw.id, conversationId: raw.conversationId, type: raw.type || text, content: raw.content || , senderId: raw.from || raw.senderId, direction: (raw.from || raw.senderId) currentUserId ? out : in, status: raw.status || sent, createdAt: raw.createdAt || raw.timestamp || Date.now() }; }direction用来决定气泡在左边还是右边不要用昵称判断。serverId和id分开后发送失败重试、服务端回执替换、历史消息去重都有依据。图片消息的content建议存对象包含缩略图、原图、宽高和过期时间不要只存一个 URL后面讲裂图问题时会用到。3. 跑通首条消息环境、参数表与发送链路拿到资源后先别改业务代码按“起服务、配参数、发首条消息”的顺序走一遍。PC 端网页即时聊天依赖浏览器长连接和跨域策略本地直接双击 HTML 往往跑不起来常见做法是用本地静态服务起一个固定端口再把云服务控制台里的应用标识、当前用户、鉴权 token 配进去。这一章的操作目标很明确让页面能登录、能连上、能发出一条文本消息并在会话列表看到最后一条消息。3.1 本地起服务端口、静态资源和 WebSocket 协议先在资源根目录看包管理器锁文件。有pnpm-lock.yaml就用 pnpm有package-lock.json就用 npm不要混用否则依赖树不一致时会出现“本地能跑、换机器白屏”的翻车现场。启动命令里显式指定端口方便后面配回调地址和调试多标签页。# 在资源根目录执行先确认 Node 版本满足依赖要求 node -v # 以 pnpm 为例如果资源包是 npm则改用 npm install corepack enable pnpm install # 起本地开发服务固定端口避免每次随机端口导致回调地址对不上 pnpm dev --host 0.0.0.0 --port 5173--host 0.0.0.0是为了让同一局域网内的另一台设备访问方便双端联调。--port 5173只是示例真正要改的是云服务控制台里的本地回调或跨域白名单端口不一致时登录回调会被拦。启动后先打开浏览器控制台看 WebSocket 连接地址确认页面用的是ws://还是wss://本地开发用ws部署后必须切到wss否则 HTTPS 页面会被浏览器拦截混合内容。提示本地起服务后不要急着改 UI先用两个不同账号登录两个浏览器标签确认双方都能看到在线状态再做样式。3.2 初始化参数表心跳、重连、鉴权别拍脑袋初始化参数不要散落在代码里统一放环境变量或配置文件。下面这张表是这类 PC 端 WebIM Demo 最常见的参数集合具体字段名以资源包里的适配层为准但含义基本一致。参数建议值作用常见错误appId控制台分配应用标识写死在组件里换环境忘记改userId登录后注入当前用户唯一标识用昵称当 ID改名后会话错乱token服务端短期签发鉴权凭证前端写死长期 token泄露后无法收口heartbeat2030 秒心跳保活设得太短移动端耗电太长掉线发现慢reconnectBase1500 毫秒重连基础间隔固定 1 秒无限重试服务端被打满historyLimit2030 条历史消息分页一次拉 200 条首屏卡顿// src/im/client.js // 页面只引用这个单例避免每个组件都 new 一个连接 import { IMAdapter } from ./adapter; export const imClient new IMAdapter({ appId: import.meta.env.VITE_IM_APP_ID, userId: sessionStorage.getItem(im_user_id) || , token: sessionStorage.getItem(im_token) || , heartbeat: 25000, reconnect: { base: 1500, max: 30000, retries: 8 }, historyLimit: 30 });heartbeat设 25 秒是折中值低于 20 秒会增加无效流量高于 30 秒断线发现会变慢。reconnect.base不是越大越好1.5 秒适合本地和办公网公网弱网可以调到 3 秒。retries到 8 次后停止自动重连页面显示“连接已断开点击重试”把决定权交回用户避免后台标签页长期空转。3.3 首条消息验证本地回显与服务端回执对账发送链路要验证的不只是“消息发出去了”还要看本地回显、服务端回执、会话列表最后一条消息是否一致。推荐先做本地临时消息再等服务端回执替换serverId。这样用户点发送后界面立刻有反馈失败时也能标红重试。// src/chat/send-text.js export async function sendText({ im, conversationId, text, appendLocal, patchStatus }) { const content text.trim(); if (!content) return; const localId local_${Date.now()}_${Math.random().toString(16).slice(2)}; appendLocal({ id: localId, conversationId, type: text, content, status: sending, createdAt: Date.now() }); try { const remote await im.sendText({ conversationId, content }); patchStatus(localId, { status: sent, serverId: remote.id, createdAt: remote.createdAt || Date.now() }); } catch (err) { patchStatus(localId, { status: failed }); throw err; } }localId只在本机有效用来定位正在发送的气泡。remote.id是服务端消息 ID拿到后要写回消息对象后续历史分页、已读回执、去重都靠它。patchStatus不要直接改原对象引用很多前端框架对深层对象修改不敏感容易出现“状态改了但界面没更新”的问题。发送失败后不要自动无限重试保留失败态让用户点一下重发这是聊天页的后悔药。4. 会话列表与消息分页排序、未读数、滚动位置首条消息跑通后第二个容易翻车的地方是会话列表和消息分页。会话列表不是简单按时间倒序置顶、免打扰、最后消息时间、未读数都会影响顺序。消息分页也不是把历史消息往前一塞就完事向上翻页时滚动位置一跳用户就会失去阅读上下文。这一章把这三个硬骨头拆开处理代码可以直接对照资源里的会话组件改。4.1 会话排序置顶、免打扰、最后消息时间排序规则要先定死再写代码。常见优先级是置顶会话在前免打扰会话靠后其余按最后消息时间倒序。不要用updatedAt和lastMessageAt混着排前者可能被“标记已读”更新后者才是用户感知的聊天时间。每次收到新消息、发送成功、标记已读后都走同一个排序函数避免列表在不同操作后顺序不一致。// src/conversation/sort.js export function sortConversations(items) { return [...items].sort((a, b) { if (a.pinned ! b.pinned) return a.pinned ? -1 : 1; // 置顶优先 if (a.muted ! b.muted) return a.muted ? 1 : -1; // 免打扰靠后 return (b.lastMessageAt || 0) - (a.lastMessageAt || 0); // 最近消息倒序 }); }items要先做浅拷贝再排序不要直接改原数组否则某些状态管理库会认为引用没变。pinned和muted用布尔值不要用 0/1 混用后面做多选筛选时容易出错。lastMessageAt统一用毫秒时间戳服务端返回秒级时间戳时在适配层乘 1000别让排序函数承担时区转换。4.2 向上翻页保持 scrollTop 的三个变量消息分页最怕“加载更多后跳到最上面”。正确做法是在插入历史消息前记录三个值scrollHeight、scrollTop、插入后的新scrollHeight。插入完成后把scrollTop调整为“原滚动距离 新增高度”这样视口内容不动用户感觉不到跳动。// src/message/load-more.js export async function loadMore({ im, conversationId, cursor, container, render }) { const prevHeight container.scrollHeight; const prevTop container.scrollTop; const page await im.fetchHistory({ conversationId, cursor, limit: 30 }); const fragment document.createDocumentFragment(); page.items.forEach(item fragment.appendChild(render(item))); container.prepend(fragment); // 新增内容撑高了多少就把滚动位置补回多少 container.scrollTop prevTop (container.scrollHeight - prevHeight); return page.nextCursor; }cursor用服务端返回的下一页游标不要用页码聊天消息会不断新增页码分页容易重复或漏消息。limit设 30 是比较稳的值太小请求频繁太大首屏渲染压力高。render返回的 DOM 节点要先挂到DocumentFragment一次性插入避免逐条prepend造成多次重排。4.3 未读数与已读回执状态收敛避免红点复发未读数常见 bug 是“进入会话红点消失刷新后又回来”。原因通常是本地清零了但没有把已读回执发给服务端或者服务端回执回来后又用旧会话数据覆盖了本地状态。处理原则是进入会话先本地清零再发已读回执回执失败不阻塞 UI但下次进入同一会话要补发。// src/conversation/read.js export function markConversationRead({ list, conversationId, im }) { const item list.find(c c.id conversationId); if (!item || item.unread 0) return; item.unread 0; im.markRead({ conversationId, lastReadAt: Date.now() }).catch(() { // 失败不弹窗下次进入会话再补一次 }); }lastReadAt用当前时间不要用最后一条消息时间否则用户只读到一半时会把后面的消息也标成已读。如果服务端支持按消息 ID 标记已读优先传lastReadMessageId比时间戳更精确。未读数更新后要重新跑一次会话排序但不要把当前会话顶到最前除非它本来就有新消息。5. 避坑与排查PC 网页即时聊天最容易翻车的 5 个现场这套 Demo 在本地跑通不难难的是换到真实网络、真实账号、真实构建产物后还能稳定。下面这 5 个现场是我在类似聊天页里反复遇到的现象看起来各不相同根因大多集中在连接态、资源地址、消息去重和构建环境上。每条按“现象 → 原因 → 解决”拆开方便排查时直接对照。5.1 刷新后掉线连接态没有持久化现象页面刷新后消息还能看但发不出去控制台提示未连接。原因连接实例只存在内存里刷新后页面重新初始化登录态还在但长连接没恢复。解决在应用启动时先读登录态再主动调用一次connect连接成功前输入框置灰。不要把connect写在登录按钮的点击事件里刷新页面不会触发点击。// src/im/bootstrap.js export async function bootstrapIM({ im, hasToken }) { if (!hasToken) return { status: guest }; try { await im.connect(); return { status: connected }; } catch (err) { return { status: disconnected, reason: err.message }; } }hasToken只判断有没有登录凭证不判断连接是否可用。连接失败后不要立刻清 token先提示重试连续三次失败再走登录失效流程。5.2 图片消息裂图URL 过期与跨域现象刚发的图片能看过一段时间或换设备后裂图。原因图片 URL 是临时地址带过期签名或者页面域名不在资源白名单里。解决消息体里存对象存储的永久标识渲染时再换临时 URL上传失败时保留本地预览图并标记失败。不要直接把控制台里的临时 URL 写死进消息内容。5.3 消息重复重连回放与本地回显叠加现象断网重连后同一条消息出现两次一条是本地回显一条是服务端推送。原因发送成功后没有用serverId替换本地消息或者重连时拉取历史消息没有去重。解决消息列表按serverId建索引合并时优先保留服务端字段本地临时消息拿到回执后删除或替换。// src/message/dedupe.js export function mergeMessages(oldList, incoming) { const map new Map(oldList.map(m [m.serverId || m.id, m])); for (const msg of incoming) { const key msg.serverId || msg.id; const old map.get(key); if (old old.id ! msg.id) continue; // 同一服务端 ID 只保留一份 map.set(key, { ...old, ...msg }); } return [...map.values()].sort((a, b) a.createdAt - b.createdAt); }key优先用serverId没有时退回本地id。合并后按createdAt排序不要依赖数组插入顺序。5.4 多标签页登录同一账号被顶下线现象同一账号开两个标签页一个能发消息另一个提示被踢。原因服务端限制单端登录后连接的标签页顶掉前一个。解决要么产品上明确单端策略要么用BroadcastChannel或localStorage事件做标签页主从只允许一个标签持有连接其他标签转发发送请求。不要在两个标签各自建连否则消息回执会乱。5.5 构建后白屏环境变量写死现象本地开发正常打包部署后白屏控制台报undefined is not a function或连接地址为空。原因环境变量只在开发服务器注入构建时没有替换或者变量名少了前缀。解决把appId、连接地址、资源域名统一放构建环境配置打包后先用静态服务打开检查。不要用window.__CONFIG__临时挂载后忘记清理。注意排查顺序先看控制台网络面板再看应用状态最后看代码。聊天页的问题一半是连接没建立一半是消息状态没收口不要一上来就怀疑 SDK。6. 交付前的三个验证双标签互发、刷新恢复、弱网重连这套 Demo 要交付前我会固定跑一遍三个验证不靠“看起来能用”。第一个是双标签互发两个浏览器标签登录不同账号A 发三条、B 回两条检查顺序、已读、会话列表最后一条是否一致。第二个是刷新恢复在会话内刷新页面检查会话是否还在、最近 30 条消息是否还能拉回、输入框草稿有没有丢。第三个是弱网重连断网 10 秒再恢复看消息是否重复、失败消息是否能重发、连接状态是否从“重连中”回到“已连接”。验证项操作通过标准双标签互发A/B 两个账号各开一个标签消息顺序一致未读数正确刷新恢复在会话内按 F5会话不丢历史消息可翻页弱网重连断网 10 秒后恢复不重复、不丢消息可手动重试多标签同账号同账号开两个标签后登录者顶掉前者不出现双连接构建产物打包后用静态服务打开环境变量有值WebSocket 地址正确从那以后我每次接聊天页都先让两个标签互相发三条消息再刷新一次看会话是否还在。这个习惯看起来笨但帮我省过两次凌晨排障。希望帮到你。本文还有配套的精品资源点击获取