站长朋友们，大家好呀，最近基于ZBlog 开发了一款轻量级的即时聊天室插件，不用依赖第三方的IM 服务，纯PHP + 原生JS 就实现了即时聊天、@提醒、在线列表、图片上传等核心功能，整个插件轻量化且适配 ZBlog 的插件生态。今天就把开发过程中的核心思路、即时通信的实现方式，还有一些巧思和技术细节拆解出来，不管是刚接触 ZBlog 插件开发的朋友，还是想做轻量 IM 功能的开发者，都能参考借鉴。一、插件整体架构设计：贴合ZBlog 生态，目录与文件分工清晰
做ZBlog 插件首先要贴合它的开发规范，这款聊天室插件的目录结构非常简洁，核心分为 PHP 后端逻辑、CSS 样式、JS 前端交互三大块，还有 ZBlog 插件必备的入口和配置文件，整体目录如下：wensha_chats/├── class/ # 核心业务类目录│ └── class.chat.php # 聊天室所有后端逻辑封装├── css/ # 样式目录│ └── style.css # 聊天室前端样式├── js/ # 前端交互目录│ └── script.js # 即时通信、DOM操作核心JS├── include.php #ZBlog插件注册、钩子挂载入口├── main.php # 插件后台配置页面└── uploads/ # 图片上传存储目录
核心设计思路是前后端分离逻辑，后端只做数据处理，前端负责交互和渲染，同时把所有后端业务逻辑封装到WenshaChat类中，保证代码的可维护性，这也是 PHP 开发的基本规范，避免全局函数和变量的混乱。二、核心：纯PHP+JS 实现即时通信，轮询方案的轻量化落地
做轻量IM 功能，不用一开始就上 WebSocket（需要服务器配置，对新手不友好），定时轮询是最适合的方案，这款插件就是用「前端定时请求后端，拉取最新消息」的方式实现即时通信，核心逻辑在 JS 的轮询函数和 PHP 的消息获取方法中，完全原生代码，无任何框架依赖。1. 后端 PHP：封装消息获取与存储，为轮询提供数据接口
后端在class.chat.php中封装了getNewMessages方法，专门为前端轮询提供最新消息，核心逻辑是根据前端传递的最后一条消息 ID，筛选出比该 ID 更新的消息，避免重复返回数据，减少服务器压力：// 摘自class.chat.phppublic functiongetNewMessages($last_id = 0, $limit = 50) {if ($last_id == 0) {return $this->getRecentMessages($limit); // 首次加载获取最近50条}$msgs = $this->readTodayMessages(); // 读取今日消息文件if (empty($msgs)) return [];$new = [];foreach ($msgs as $m) {$id_part = (int)explode('-', $m['id'])[0];if ($id_part > $last_id) $new[] = $m;// 筛选最新消息}return $new;}
消息存储也做了轻量化处理，按年月日分目录、按天生成消息文件，比如chats/2025/09/21_chatalogs.php，既方便后续清理历史记录，也能提升文件读取效率，避免单文件过大：// 摘自class.chat.php：获取今日聊天文件路径private function getTodayFile() {$year = date('Y');$month = date('m');$day = date('d');$dir = $this->chatDir . $year . '/' . $month . '/';if (!file_exists($dir)) mkdir($dir, 0755, true); // 自动创建目录return $dir . $day . '_chatalogs.php';}
同时在include.php中通过 ZBlog 的钩子注册了API 路由，前端通过?chat_action=poll即可请求轮询接口，后端根据chat_action分发不同的业务逻辑，这是 ZBlog 插件实现接口的经典方式：// 摘自include.php：API路由分发functionwensha_chats_api_router() {global $zbp;$action = GetVars('chat_action', 'GET');if (empty($action)) return;require_once $blogpath . 'zb_users/plugin/wensha_chats/class/class.chat.php';$chat = new WenshaChat();header('Content-Type: application/json; charset=utf-8');// 返回JSON格式switch ($action) {case 'poll': // 轮询接口$last_id = (int)GetVars('last_id', 'GET', 0);$limit = (int)GetVars('limit', 'GET', 50);$data = $chat->getNewMessages($last_id, $limit);$online_users = $chat->getOnlineUsers();echo json_encode(['code'=>0, 'data'=>$data, 'online_users'=>$online_users]);break;// 其他接口：send/upload/history...}exit;}// 挂载ZBlog钩子，让接口生效Add_Filter_Plugin('Filter_Plugin_Index_Begin', 'wensha_chats_api_router');
2. 前端 JS：定时轮询 + 消息渲染，实现 “即时” 效果
前端在script.js中设置3 秒一次的定时轮询（可自定义POLL_INTERVAL），通过fetch请求后端轮询接口，获取最新消息后立即渲染到页面，同时更新本地的最后消息 ID，形成闭环：// 摘自script.js：核心轮询函数const POLL_INTERVAL = 3000; // 3秒轮询一次let lastMessageId = 0;let pollTimer = null;function pollMessages(immediate = false) {if (!immediate && pollTimer) return;// 请求后端轮询接口，携带最后消息IDfetch('?chat_action=poll&last_id=' + lastMessageId + '&username=' + encodeURIComponent(currentUsername)).then(res => res.json()).then(data => {if (data.code === 0) {if (data.data.length) {appendMessages(data.data, false); // 渲染新消息// 更新最后消息ID为最新的时间戳const ids = data.data.map(m => parseInt(m.id.split('-')[0]));lastMessageId = Math.max(...ids, lastMessageId);}if (data.online_users) {updateOnlineList(data.online_users); // 更新在线列表}}// 定时执行轮询，形成循环if (pollTimer) clearTimeout(pollTimer);pollTimer = setTimeout(() => pollMessages(true), POLL_INTERVAL);}).catch(() => { // 请求失败重连，保证稳定性pollTimer = setTimeout(() => pollMessages(true), POLL_INTERVAL); });}// 初始化轮询pollMessages(true);
这里有个小细节：轮询失败后会自动重新发起请求，避免因网络波动导致聊天中断，同时渲染消息时会做去重处理，通过消息ID 判断是否已渲染，防止重复消息出现。三、那些提升体验的巧思：@提醒、在线列表、动态配色
除了核心的即时通信，插件的很多细节功能都是通过简单的PHP+JS 实现，没有复杂的技术，但大幅提升了使用体验，这些也是开发轻量 IM 功能时可以借鉴的点。1. @用户提醒：正则匹配 + 本地未读计数，实现精准提醒
@提醒的核心分为后端解析和前端高亮 + 未读计数两步，后端通过正则匹配消息内容中的@用户名，前端判断是否 @当前用户，若未打开聊天面板则显示未读徽章，同时播放提示音：// 摘自class.chat.php：提取@的用户名public functionparseMentions($text) {// 匹配中文、英文、下划线的用户名，兼容绝大多数昵称格式preg_match_all('/@([\w\x{4e00}-\x{9fa5}-]+)/u', $text, $matches);return array_unique($matches[1] ?? []); // 去重，避免重复@同一用户}
// 摘自script.js：渲染消息时判断@当前用户if (msg.mentions && msg.mentions.includes(currentUsername)) {const isRead = readMentions.includes(msg.id);if (!isPanelOpen && !isRead) {if (!unreadMentions.includes(msg.id)) {unreadMentions.push(msg.id);mentionCount++;updateBadge(); // 更新未读徽章playNotificationSound(); // 播放提示音}}// 高亮@当前用户的内容const currentUserEscaped = escapeRegExp(currentUsername);const regex = new RegExp(`@${currentUserEscaped}(?![\\-\\w\\u4e00-\\u9fa5])`, 'g');html = html.replace(regex, `<span class="at-highlight">@${escapeHtml(currentUsername)}</span>`);}
同时做了快速@功能：点击用户头像或在线列表，自动在输入框插入@用户名，不用手动输入，通过insertAtCursor函数实现光标位置插入文本，这是原生 JS 操作输入框的经典方法。2. 在线列表：基于时间戳的轻量判断，无需数据库
没有用数据库存储用户在线状态，而是通过本地文件+ 时间戳实现：用户每次发起请求（轮询 / 发消息 / 上传）时，后端更新该用户的在线时间戳到online.json文件，判断在线状态时，只要时间戳在 5 分钟内，就认定为在线，同时自动清理过期的用户信息：// 摘自class.chat.php：更新在线状态public functionupdateOnlineStatus($username) {if (empty($username)) return;$online = $this->getOnlineRaw();$online[$username] = time(); // 更新当前用户时间戳$expire = time() - 300; // 5分钟有效期// 清理过期用户foreach ($online as $name => $last) {if ($last < $expire) unset($online[$name]);}file_put_contents($this->onlineFile, json_encode($online), LOCK_EX); // 加锁避免并发问题}
前端轮询时后端同时返回在线用户列表，前端直接渲染，实现在线列表的实时更新，整个过程不用数据库，轻量化且高效。3. 动态配色方案：按用户名哈希分配，支持自定义
为了让不同用户的消息气泡有明显区分，插件做了按用户名哈希分配配色的功能，同时支持用户自定义配色，后端存储配色方案，前端根据用户名的字符编码做哈希计算，取模分配配色，保证同一用户始终对应同一种配色：// 摘自script.js：根据用户名分配配色function getSchemeForMessage(msg, isMine) {if (msg.color_scheme !== undefined && msg.color_scheme >= 0 && msg.color_scheme < colorSchemes.length) {return colorSchemes[msg.color_scheme]; // 自定义配色}// 哈希计算：将用户名转为数字哈希let hash = 0;const username = msg.username;for (let i = 0; i < username.length; i++) {hash = ((hash << 5) - hash) + username.charCodeAt(i);hash |= 0;}const index = Math.abs(hash) % colorSchemes.length; // 取模分配return colorSchemes[index];}
配色方案的配置在ZBlog 后台实现（main.php），支持添加 / 删除自定义配色，且默认配色不可修改，贴合 ZBlog 的后台操作逻辑。四、ZBlog 插件开发的关键细节：适配生态，保证安全性
做ZBlog 插件，除了实现功能，还要贴合 ZBlog 的插件生态，同时保证代码的安全性，这部分也是新手容易忽略的点，这款插件做了以下处理：1. 遵循 ZBlog 插件规范：注册、安装、钩子挂载
ZBlog 插件必须实现RegisterPlugin、ActivePlugin_xxx、InstallPlugin_xxx等函数，在include.php中完成插件注册、钩子挂载、初始化目录等操作，同时安装插件时自动创建所需目录和配置文件：// 摘自include.php：ZBlog插件核心注册RegisterPlugin("wensha_chats", "ActivePlugin_wensha_chats");// 激活插件时挂载钩子functionActivePlugin_wensha_chats() {Add_Filter_Plugin('Filter_Plugin_Index_End', 'wensha_chats_output'); // 输出前端代码Add_Filter_Plugin('Filter_Plugin_Index_Begin', 'wensha_chats_api_router');// 接口路由wensha_chats_create_dirs(); // 初始化目录}// 安装插件时初始化配置functionInstallPlugin_wensha_chats() {global $zbp;wensha_chats_create_dirs();$defaultScheme = ['bubbleBg' => '#E3F2FD','bubbleText' => '#0D47A1','avatarBg' => '#1E88E5','is_default' => true];$zbp->Config('wensha_chats')->color_schemes = [$defaultScheme];$zbp->SaveConfig('wensha_chats');}
2. 安全性处理：过滤输入，限制文件上传，加锁写文件
前端输入过滤：所有用户输入的内容都通过strip_tags、htmlspecialchars过滤，避免 XSS 攻击；文件上传限制：仅支持jpg、png、webp 等图片格式，限制文件大小，上传目录添加.htaccess禁止执行脚本；并发处理：写文件时添加LOCK_EX锁，避免多用户同时发消息导致的文件内容错乱；权限控制：插件后台配置页面通过$zbp->CheckRights('root')限制只有管理员可访问。五、总结：轻量IM 开发的核心思路
这款ZBlog 聊天室插件的开发核心，就是用最简单的技术实现核心功能，同时兼顾体验和安全性，没有依赖任何第三方框架和服务，纯 PHP + 原生 JS 就能落地，对于轻量 IM 场景（个人博客、小型网站）完全够用。即时通信用定时轮询即可，无需强求WebSocket，3 秒的轮询间隔在小型场景下完全能实现 “即时” 效果，且开发和部署成本极低；数据存储轻量化，按时间分文件存储，不用数据库，适合小型插件，同时方便后续清理历史记录；前后端职责清晰，后端只做数据处理和接口返回，前端负责交互和渲染，降低耦合度；细节体验提升靠小功能实现，比如@提醒、快速插入、在线列表，这些功能技术难度不高，但能大幅提升用户体验；开发第三方插件必须贴合平台生态，比如ZBlog 的钩子、配置、权限体系，遵循规范才能让插件稳定运行。这款插件的所有代码都是原生的，没有复杂的语法，新手也能轻松看懂和修改，大家可以在此基础上扩展功能，比如添加消息撤回、表情包库、私聊功能等，核心的即时通信框架已经搭建完成，扩展起来非常方便。该Zblog插件下载：请关注微信公众号"文煞站长笔记网"，私聊回复"018"获取下载链接！
