大家好，最近基于 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.php
public function getNewMessages($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路由分发
function wensha_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;
// 请求后端轮询接口，携带最后消息ID
fetch('?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. @用户提醒：正则匹配 + 本地未读计数，实现精准提醒
@提醒的核心分为后端解析和前端高亮 + 未读计数两步，后端通过正则匹配消息内容中的@用户名，前端判断是否 @当前用户，若未打开聊天面板则显示未读徽章，同时播放提示音：
后端 PHP 正则解析 @用户：
// 摘自class.chat.php：提取@的用户名
public function parseMentions($text) {
// 匹配中文、英文、下划线的用户名，兼容绝大多数昵称格式
preg_match_all('/@([\w\x{4e00}-\x{9fa5}-]+)/u', $text, $matches);
return array_unique($matches[1] ?? []); // 去重，避免重复@同一用户
}
前端 JS 高亮 + 未读计数：
javascript
运行
// 摘自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>@${escapeHtml(currentUsername)}</span>`);
}同时做了快速 @功能：点击用户头像或在线列表，自动在输入框插入@用户名，不用手动输入，通过insertAtCursor函数实现光标位置插入文本，这是原生 JS 操作输入框的经典方法。
2. 在线列表：基于时间戳的轻量判断，无需数据库
没有用数据库存储用户在线状态，而是通过本地文件 + 时间戳实现：用户每次发起请求（轮询 / 发消息 / 上传）时，后端更新该用户的在线时间戳到online.json文件，判断在线状态时，只要时间戳在 5 分钟内，就认定为在线，同时自动清理过期的用户信息：
// 摘自class.chat.php：更新在线状态
public function updateOnlineStatus($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");
// 激活插件时挂载钩子
function ActivePlugin_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(); // 初始化目录
}
// 安装插件时初始化配置
function InstallPlugin_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 的钩子、配置、权限体系，遵循规范才能让插件稳定运行。
这款插件的所有代码都是原生的，没有复杂的语法，新手也能轻松看懂和修改，大家可以在此基础上扩展功能，比如添加消息撤回、表情包库、私聊功能等，核心的即时通信框架已经搭建完成，扩展起来非常方便。
