简介：这是一套基于layim与环信实现的PC端网页即时聊天前端Demo，面向需要快速搭建WebIM界面的前端开发者与学习者。资源以layui生态的layim组件为界面骨架，接入环信作为消息通道，演示了文字与表情发送、联系人列表等核心交互，联系人数据采用本地假数据，替换为自己的接口即可复用，环信部分需换成自己的key，测试时仅张三与李四两个账号可互相通讯。压缩包共190个文件，约1.7MB，其中33个js承担逻辑与接口调用，14个css与6个html负责页面结构与样式，另有大量gif、png、jpg等图片资源用于表情与界面素材，以及字体、图标、json配置等辅助文件。目前已有1529人学习下载。读者可借此理解layim与环信的结合方式、消息收发流程与前端目录组织，并在此基础上替换接口与key，扩展图片、文件发送能力，快速落地自己的网页聊天模块。
1. 从一份能跑通的网页聊天 Demo 说起
前阵子帮朋友看一个客服系统的前端改造，需求很直接：把原来嵌在页面角落的咨询窗口，换成一套带会话列表、聊天窗口、消息记录的完整网页即时聊天界面。他手里只有一份 layim 加环信 PC 端 WebIM 的聊天 Demo，跑起来能发消息，但想改成自己的业务就不知道从哪下手。我花了一个下午把这份源码拆了一遍，发现它其实是个很典型的「UI 框架 + 云通信 SDK」组合：layim 负责把聊天界面搭出来，环信负责消息通道和会话管理。对想快速做出一套能用的网页聊天页面的开发者来说，这个组合省掉了从零写 UI 和自建长连接服务的大头工作量。这篇就把这份 Demo 从目录结构、初始化流程、消息收发到二次开发改造，按我实际拆解的路径讲一遍，新手能照着跑，熟手能直接看关键实现。
2. 技术选型与目录结构：layim 和环信各自负责什么
2.1 为什么是 layim 加环信这套组合
网页即时聊天这个场景，拆开看其实有两块硬骨头。一块是界面：会话列表、好友分组、聊天窗口、消息气泡、输入框、表情面板、右键菜单，这些交互细节堆起来工作量不小。另一块是通信：长连接维持、消息可靠投递、离线消息、多端同步、会话已读未读，自己从零做一套 IM 后端，成本和运维压力都很大。
layim 是 layui 生态里的一个即时聊天 UI 模块，它把上面说的那套界面结构都封装好了，提供了一套配置式的 API，你给它数据，它渲染界面，你监听它的回调，处理用户操作。环信则提供 WebIM SDK，负责消息通道。两者结合，前端开发者只需要做一件事：把环信 SDK 收到的消息，转成 layim 能识别的数据格式喂进去；把 layim 里用户的操作，转成环信 SDK 的调用发出去。中间这层「翻译」逻辑，就是这个 Demo 的核心。
常见做法是再包一层适配器，把环信的回调统一转成 layim 的事件，这样业务代码不用直接碰 SDK。这份 Demo 里虽然没做很厚的抽象，但思路是清晰的。
2.2 目录结构长什么样
拿到源码包，先别急着跑，把目录扫一遍心里有底。这类 Demo 的目录结构通常是这样组织的：
webim-demo/ ├── index.html # 入口页面，聊天界面容器 ├── login.html # 登录页，输入账号进入聊天 ├── css/ │ ├── layui.css # layui 基础样式 │ └── layim.css # layim 聊天界面样式 ├── js/ │ ├── layui.js # layui 核心 │ ├── layim.js # layim 聊天模块 │ ├── jquery.min.js # 依赖库 │ ├── websdk.js # 环信 WebIM SDK │ └── app.js # 业务逻辑，初始化和消息桥接 ├── img/ # 头像、表情、图标资源 └── config.js # 环信 appKey 等配置关键文件就三个：index.html是界面骨架，app.js是业务逻辑，config.js放环信的应用标识。其余都是依赖库和静态资源。理解这个结构之后，改造的入口就很明确了——界面改index.html和样式，逻辑改app.js，连接配置改config.js。
2.3 环信 SDK 的引入方式
环信 WebIM SDK 一般通过 script 标签直接引入，或者用模块化方式加载。这份 Demo 用的是前者，简单直接：
<!-- 先引入依赖 --> <script src="js/jquery.min.js"></script> <script src="js/layui.js"></script> <script src="js/websdk.js"></script> <!-- 业务逻辑放最后 --> <script src="js/config.js"></script> <script src="js/app.js"></script>这里有个顺序问题要注意：websdk.js必须在app.js之前加载，因为app.js里初始化连接时会直接引用 SDK 暴露的全局对象。config.js放在app.js前面，是为了让配置项在业务逻辑执行时已经就绪。这个顺序如果搞反，控制台会报WebIM is not defined之类的错误，是新手最容易翻车的地方。
3. 初始化流程拆解：从登录到建立连接
3.1 配置环信应用参数
在config.js里，需要填的是环信应用的基本信息。这些参数在环信管理后台创建应用后能拿到：
// config.js window.imConfig = { // 环信应用标识，在管理后台创建应用后获取 appKey: 'your_app_key_here', // 是否开启日志，调试阶段建议打开 isDebug: true, // 是否使用 HTTPS https: true, // 心跳间隔，默认即可 heartBeatWait: 30000 };appKey是环信区分不同应用的唯一标识，格式通常是一串由井号分隔的字符串。isDebug打开后，SDK 会在控制台输出连接状态、消息收发等日志，排查问题时非常有用，上线前再关掉。https要和你的页面协议保持一致，页面是 https 就填 true，否则浏览器会拦截混合内容。
提示：
appKey属于应用凭证，不要直接提交到公开仓库。常见做法是构建时通过环境变量注入，或者放在服务端下发的配置接口里。
3.2 初始化连接并登录
连接建立和登录是两步。先创建连接对象，再调用登录接口。这段逻辑一般放在页面加载完成后执行：
// app.js 初始化部分 var conn = null; function initIM() { // 创建连接实例，传入配置 conn = new WebIM.connection({ appKey: window.imConfig.appKey, https: window.imConfig.https, isDebug: window.imConfig.isDebug, heartBeatWait: window.imConfig.heartBeatWait }); // 注册全局回调，消息、状态变化都从这里出来 conn.listen({ onOpened: function () { console.log('连接已建立'); // 连接成功后加载会话列表 loadSessionList(); }, onClosed: function () { console.log('连接已断开'); }, onTextMessage: function (message) { // 收到文本消息，转给 layim 渲染 handleIncomingMessage(message); }, onError: function (error) { console.error('连接出错', error); } }); } function loginIM(userId, password) { var options = { user: userId, pwd: password, // 自动登录，刷新页面不用重新输密码 apiUrl: WebIM.config.apiURL }; conn.open(options); }conn.listen注册的回调是整个消息流的入口。onOpened在连接建立后触发，适合在这里做会话列表的初始化加载。onTextMessage是收到文本消息的回调，参数message里包含发送方、接收方、消息内容、时间戳等字段。onError一定要处理，否则连接失败时页面没有任何反馈，用户会以为卡死了。
conn.open的options里，user和pwd是环信账号体系里的用户凭证。这个 Demo 里通常是写死几个测试账号，或者从登录页表单获取。apiUrl一般用 SDK 默认值，除非你有自己的代理层。
3.3 用 layim 渲染界面骨架
连接建立之后，要把界面搭起来。layim 的初始化是配置式的，你给它一套数据结构，它负责渲染：
// 初始化 layim 界面 layui.use('layim', function () { var layim = layui.layim; layim.config({ // 基础配置 brief: false, title: '我的聊天', isAudio: true, isVideo: false, // 聊天窗口右侧的成员列表 right: 'members', // 初始化时加载的数据 init: { // 当前登录用户信息 mine: { id: currentUserId, username: currentUserName, avatar: currentUserAvatar, status: 'online' } }, // 监听发送消息 sendMessage: function (data) { // data 包含 to、content、type 等字段 sendMessageToIM(data); } }); // 加载好友列表和群组 layim.on('ready', function () { loadFriendList(); }); });layim.config里的init.mine是当前用户信息，layim 用它来区分消息气泡的左右方向。sendMessage回调是用户点击发送时触发的，data里带着接收方 id、消息内容、消息类型。这个回调就是 layim 和环信之间的第一个桥接点——把 layim 的发送动作转成环信的消息发送。
layim.on('ready')在界面初始化完成后触发，适合在这里拉取好友列表和群组数据。好友列表的数据结构 layim 有固定格式，通常是一个包含friend数组的对象，每个好友有id、username、avatar、sign等字段。
4. 消息收发链路：layim 和环信之间怎么桥接
4.1 发送消息：从 layim 回调到环信 SDK
用户在聊天窗口输入内容点发送，layim 触发sendMessage回调。我们要在这个回调里调用环信 SDK 的发送接口：
// 把 layim 的发送动作转成环信消息 function sendMessageToIM(data) { // data.to 是接收方 id，data.content 是消息内容 var id = conn.getUniqueId(); // 生成本地消息 id var msg = new WebIM.message('txt', id); msg.set({ msg: data.content, to: data.to, // 聊天类型：single 单聊，group 群聊 chatType: data.type === 'friend' ? 'single' : 'group', // 发送成功回调 success: function (id, serverMsgId) { console.log('消息发送成功', serverMsgId); }, // 发送失败回调 fail: function (e) { console.error('消息发送失败', e); // 失败时给用户提示，常见做法是标红重发 } }); conn.send(msg.body); }conn.getUniqueId()生成一个本地唯一的消息 id，用于消息去重和状态追踪。WebIM.message的第一个参数是消息类型，txt表示文本，还有img、file、audio等类型。msg.set里的chatType决定是单聊还是群聊，这个值要根据 layim 传来的data.type判断。
success和fail两个回调必须都处理。发送成功时，通常要把消息状态更新为「已送达」；发送失败时，要给用户一个明确的重发入口。很多 Demo 只处理成功回调，结果网络抖动时消息丢了用户完全不知道，这是实际使用中最容易被投诉的点。
4.2 接收消息：从环信回调到 layim 渲染
收到消息的处理路径和发送相反。环信 SDK 的onTextMessage回调拿到消息后，要转成 layim 能识别的格式，再调用 layim 的接口渲染：
// 处理收到的消息 function handleIncomingMessage(message) { // message 里包含 from、to、data、type 等字段 var fromId = message.from; var content = message.data; // 判断消息来源，决定渲染到哪个会话 var chatType = message.type === 'chat' ? 'friend' : 'group'; // 调用 layim 接口，把消息推到对应会话窗口 layui.use('layim', function () { var layim = layui.layim; // 获取当前会话，如果不存在则创建 layim.getMessage({ username: getFriendName(fromId), avatar: getFriendAvatar(fromId), id: fromId, type: chatType, content: content, timestamp: message.time || Date.now() }); }); }layim.getMessage是 layim 提供的接收消息接口。它会自动判断当前是否打开了对应的聊天窗口：如果打开了，直接追加消息气泡；如果没打开，就在会话列表里更新未读数。username、avatar这些信息需要从本地的好友缓存里查，所以初始化时把好友列表存一份在内存里是必要的。
timestamp字段用于消息排序和显示时间分隔线。环信返回的message.time是服务端时间，如果拿不到就用本地时间兜底。
4.3 会话列表和未读数的维护
会话列表是聊天界面的门面，用户打开页面第一眼看到的就是它。layim 的会话列表数据通过layim.config的init或者后续的layim.addList接口来维护：
// 加载会话列表 function loadSessionList() { // 从环信拉取最近会话，或者从本地缓存读 var sessions = getRecentSessions(); layui.use('layim', function () { var layim = layui.layim; sessions.forEach(function (session) { layim.addList({ type: session.type, // friend 或 group username: session.name, avatar: session.avatar, id: session.id, // 未读数 unread: session.unread || 0 }); }); }); }layim.addList每调用一次就往会话列表里加一项。如果同一个会话重复添加，layim 内部会做去重，但未读数需要你自己维护。常见做法是维护一个sessionMap，收到消息时更新对应会话的未读数，用户点开会话时清零。
未读数的更新时机有三个：收到新消息时加一，用户打开会话时清零，页面初始化时从服务端或本地存储恢复。这三个时机漏掉任何一个，未读数就会不准，用户会觉得「消息提示是玄学」。
5. 避坑与常见问题排查
5.1 连接建立失败，控制台报跨域或 401
现象是页面加载后一直连不上，控制台出现跨域错误或者 401 未授权。原因通常是appKey填错、账号密码不对，或者页面协议和 SDK 配置的https不一致。解决方法是先确认config.js里的appKey和管理后台一致，再检查登录用的账号是否在环信后台注册过。如果页面是 https 而https配置填了 false，浏览器会拦截请求，把配置改成 true 即可。
5.2 消息发出去了但对方收不到
现象是自己这边显示发送成功，但对方页面没有新消息。原因可能是接收方的连接已经断开但页面没感知，或者消息发送时chatType判断错了。解决方法是先看环信后台的消息记录，确认消息是否到达服务端。如果到了服务端但对方没收到，检查接收方的onTextMessage回调是否注册成功，以及conn.listen是否在登录前就调用了。顺序错了会导致回调丢失。
5.3 layim 界面渲染出来了但发消息没反应
现象是界面正常，输入框能打字，点发送按钮没任何反应。原因是layim.config里的sendMessage回调没有正确绑定，或者回调里调用的环信发送接口抛了异常被吞掉了。解决方法是在sendMessage回调第一行加console.log，确认回调是否触发。如果触发了但没发出去，检查conn对象是否已经初始化，以及conn.send的参数格式是否正确。
5.4 刷新页面后聊天记录全没了
现象是刷新页面后，之前的聊天记录和会话列表都清空了。原因是这个 Demo 默认没有做本地持久化，所有数据都在内存里。解决方法是引入localStorage或IndexedDB，在收到消息和发送消息时把记录存下来，页面初始化时先读本地缓存再拉服务端数据。环信本身提供漫游消息接口，可以拉取历史消息，但需要额外调用。
5.5 多标签页打开时消息重复
现象是同一个账号开了两个标签页，收到消息时两个页面都弹提示，未读数也各算各的。原因是每个标签页都独立建立了一条环信连接。解决方法是常见做法用localStorage加锁，只允许一个标签页建立连接，其他标签页通过storage事件同步消息。或者干脆在业务上限制同一账号只能单页面使用。
6. 二次开发改造：换成自己的账号体系和业务数据
6.1 替换账号体系
这份 Demo 用的是环信自带的账号注册和登录。实际项目里，你通常有自己的用户系统，不想让用户再记一套环信账号。常见做法是在服务端做一层映射：用户用自己的账号登录你的系统，你的服务端用管理员权限去环信创建或查询对应的 IM 账号，然后把 IM 账号的 token 下发给前端。前端拿到 token 后调用环信的 token 登录接口，而不是用账号密码。
改造点在loginIM函数，把conn.open的options从user/pwd换成accessToken：
function loginWithToken(userId, token) { conn.open({ user: userId, accessToken: token, // 其他配置不变 }); }accessToken由你的服务端调环信 REST API 获取，有效期通常有几天，前端可以缓存起来，过期再重新拉。
6.2 接入自己的好友和群组数据
Demo 里的好友列表是写死的测试数据。实际项目里，好友关系存在你自己的数据库。改造思路是：页面初始化时调你的后端接口拉好友列表，转成 layim 需要的格式，再调layim.addList渲染。群组同理。
这里有个细节要注意：layim 的好友数据结构里，id字段必须和环信那边的用户 id 一致，否则发消息时to字段对不上，消息发不出去。常见做法是在你的用户表里存一个im_account字段，专门映射环信账号。
6.3 消息类型扩展
Demo 只处理了文本消息。实际业务里可能需要图片、文件、订单卡片等自定义消息。环信支持自定义消息类型，layim 也支持自定义消息模板。改造路径是：发送时用WebIM.message('custom', id)构造自定义消息，msg.set里带上你的业务数据；接收时在onCustomMessage回调里解析，再调 layim 的自定义消息渲染接口。
自定义消息的坑在于两端的数据格式必须约定好，而且要考虑旧版本客户端的兼容性。我一般会在消息体里加一个version字段，解析时先判断版本再走对应逻辑。
6.4 一个验证改造是否成功的小技巧
改完之后怎么确认没问题？我的习惯是开两个浏览器窗口，用两个不同账号登录，互相发消息。重点看四个点：消息是否实时到达、未读数是否正确、刷新后记录是否还在、断网重连后消息是否补上。这四个点覆盖了消息链路的主要环节，任何一个出问题都能快速定位到对应模块。
从那以后我每次改 IM 相关代码，都强制走一遍「双窗口四检查」的流程，比看日志快得多。希望帮到你。
本文还有配套的精品资源，点击获取
