基于uni-im开源框架搭建网站在线客服聊天系统实操指南
在各类网站中，右下角的在线客服聊天窗口早已十分常见，用户可通过该窗口咨询问题、留言反馈，本质就是即时通讯功能。市面上商业化的即时通讯平台成本偏高，对于仅需基础聊天、客服沟通功能的开发者而言，uni-im开源即时通讯框架是性价比极高的选择。它免费开源、支持二次开发，部署方式灵活，还可实现单聊、群聊、AI对话等功能，本文将完整讲解基于uni-im搭建匿名在线客服系统的全流程，梳理实操要点与避坑技巧。
如果看文档不清晰的话，可以看教学视频： https://www.bilibili.com/video/BV1HBER6rEbK/
一、uni-im框架简介
uni-im是适配uniapp生态的开源即时通讯框架，最大优势是部署方案丰富、支持深度二次开发，不仅能直接集成到uniapp项目中，Java、Python等其他语言开发的网站也可对接使用。
该框架原生支持一对一单聊、多人群聊，还预留了AI聊天接口。它分为两种核心使用模式：一是纯在线部署，无需接触代码，适合零基础用户，但无法自定义界面与功能；二是下载源码本地部署，可自由修改页面、删减多余模块、定制品牌样式，也是搭建专属在线客服的首选方案。
结合实际使用场景，纯在线部署存在明显短板：无法修改原生自带的侧边栏链接、不能添加自定义LOGO，界面固定且灵活性差。因此想要打造贴合自身业务的客服系统，建议直接下载源码，借助HBuilder编辑器进行本地开发与二次改造。
二、前期环境与云服务准备
（一）工具准备
开发首选HBuilder编辑器，该工具对uniapp、uni-im框架做了深度适配；若使用其他编辑器，仅需下载项目压缩包即可。
（二）项目获取与创建
- 打开DCloud插件市场，搜索
uni-im，下载项目源码并导入HBuilder，自定义项目名称（如客服demo），选择Vue3版本。 - uni-im依赖uniCloud云服务，云服务可选择支付宝云、阿里云等。对比下来支付宝云成本更低，新手推荐选用。
- 新建uniCloud服务空间：登录对应云服务账号，创建独立的服务空间，建议项目与服务空间名称保持一致，方便后期管理。首次使用可选择免费版或按量计费模式，服务空间创建后需要等待约十分钟完成初始化。
- 服务空间关联：在HBuilder中将本地项目与刚刚创建的云服务空间完成关联，云端的前端网页托管将用于后续存放打包后的项目文件，云函数、数据库也会部署在该服务空间内。
三、云端资源部署与常见问题解决
这是整个搭建流程中最容易出错的环节，主要包含云函数、公共模块、数据库的上传初始化。
- 整体初始化：在项目
unicloud目录右键启动初始化向导，执行部署与数据库初始化。直接一键上传大概率会出现红色报错，这是uni-im版本依赖带来的典型问题。 - 手动上传公共模块：项目内各类云函数依赖公共模块，批量上传会因依赖关系失败。需要进入
cloudfunction目录，找到common公共模块，逐个手动上传所有模块，这是解决上传报错的核心方法。 - 数据库与配置补全：公共模块上传完成后，重新执行云函数部署并选择覆盖；随后右键初始化云数据库，全选文件完成上传。最后单独上传数据库的
schema扩展配置，保证数据表结构正常生效。
四、客户端基础配置与消息推送开通
云端部署完成后，开始配置前端客户端，重点完成H5页面与消息推送设置。
- 基础H5配置：打开项目
manifest配置文件，切换至Web配置项，自定义应用名称；路由模式选择哈希模式，基础路径填写/，将项目部署在网站根目录。 - 开通uniPush推送服务：即时通讯的消息收发必须依赖uniPush，点击申请开通服务，进入开发者后台。仅搭建网页端客服时，可关闭安卓、iOS、鸿蒙端，只保留Web与小程序端，并关联已创建的云服务空间，完成推送服务绑定。
五、本地运行测试：原生账号聊天功能
配置全部完成后，即可在本地浏览器运行项目，测试基础聊天功能：
- 项目启动后会自动跳转登录页，该框架基于uni-id用户体系，默认必须账号登录。
- 注册两个不同账号（如admin1111、admin2222），分别在两个浏览器登录，模拟客服与普通用户。
- 获取对方用户ID，拼接访问地址传入用户ID参数，即可实现两端消息互通，文字收发、消息提醒等基础通讯功能就此跑通。
六、核心改造：实现匿名客服聊天
原生框架强制登录，而网站在线客服一般支持游客匿名咨询，这也是二次开发的核心需求，uni-im支持通过传参实现免登录匿名访问。
（一）全局配置关闭服务端登录校验
进入项目uni-config-center/config/uni-im/config.json配置文件，新增参数值use-prom，关闭服务端登录校验，允许无账号体系访问。
javascript
{
"check_mobile": false,
"customer_service_uids": false,
"conversation_grade": 0,
"get_external_userinfo": "use-param"
}如果不配置get_external_userinfo这参数，有可能在打包上线的时候出现这个错误提示：请配置登录验证回调地址
出现这问题，只需要配置一下参数，然后重新将公共模块上传到云端就可以了。
（二）匿名参数规则与地址拼接
匿名登录需要传递三个核心参数，可通过URL编码拼接在访问地址中：
- 唯一设备ID：无需真实设备ID，可用时间戳作为唯一标识符，避免重复。
- 匿名昵称：可自定义文字，也可对接IP接口，获取用户IP、省市信息作为昵称，方便客服区分访客。
- 访客头像：配置网络图片地址作为匿名用户头像。
javascript
const param = {
_id: Date.now(),
nickname: '自定义用户昵称',
avatar_file: {
url: 'https://img.yzcdn.cn/vant/cat.jpeg'
}
}
encodeURIComponent(JSON.stringify(param))
//访问地址
http://localhost:8080/#/uni_modules/uni-im/pages/index/index?login=%7B%22_id%22%3A1781015155879%2C%22nickname%22%3A%22%E8%87%AA%E5%AE%9A%E7%94%A8%E6%88%B7%E6%98%B7%E7%A7%B0%22%2C%22avatar_file%22%3A%7B%22url%22%3A%22https%3A%2F%2Fimg.yzcdn.cn%2Fvant%2Fcat.jpeg%22%7D%7D&user_id=6a26e0aac811eae460c60c92同时地址末尾需要拼接客服账号的uid，指定消息接收对象。将参数整体做URL编码后，组合成完整访问链接，访问该链接即可跳过登录，直接进入匿名聊天窗口。
（三）页面集成
在自有网站页面添加客服按钮，将拼接好的匿名聊天链接设置为按钮跳转地址。非uniapp项目也可参考官方集成示例，编写简单跳转逻辑，适配各类网站。
javascript
<template>
<a class="online-service" :href="serviceChatUrl" target="_blank" rel="noopener noreferrer" aria-label="在线客服">
<span class="online-service__icon">💬</span>
<span class="online-service__text">在线客服</span>
</a>
</template>
<script setup>
import { ref, computed, onMounted } from "vue";
const imWebUrl = "http://im.qingnian8.com";
const user_id = "6a1ff2b38be8f8513086228c";
const path = "/#/uni_modules/uni-im/pages/index/index";
const deviceId = ref("");
function initDeviceId() {
const key = "_device_id";
let id = localStorage.getItem(key);
if (!id) {
id = crypto.randomUUID();
localStorage.setItem(key, id);
}
deviceId.value = id;
}
const nickname = ref("自定义用户昵称");
const param = computed(() => ({
_id: deviceId.value,
nickname: nickname.value,
avatar_file: {
url: "https://cdn.qingnian8.com/project/avatarUrl.png",
},
}));
const serviceChatUrl = computed(() => `${imWebUrl + path}?login=${encodeURIComponent(JSON.stringify(param.value))}&user_id=${user_id}`);
onMounted(async () => {
initDeviceId();
try {
const res = await fetch("https://myip.ipip.net/");
const text = await res.text();
// 返回格式：当前 IP：119.163.1.2 来自于：中国 山东 济南 联通
const match = text.match(/当前 IP：(\d+\.\d+\.\d+\.\d+)\s+来自于：(.+?)(?:\s{2,}|$)/);
nickname.value = match ? `${match[1]}（${match[2].trim()}）` : text.trim();
} catch {
// 接口失败时保持默认昵称
}
});
</script>
<style lang="scss" scoped>
.online-service {
position: fixed;
right: 24px;
top: 50%;
z-index: 999;
display: flex;
flex-direction: column;
align-items: center;
gap: 6px;
padding: 12px 10px;
color: #fff;
text-decoration: none;
background: #1677ff;
border-radius: 12px;
box-shadow: 0 8px 20px rgba(22, 119, 255, 0.3);
transform: translateY(-50%);
transition: transform 0.2s ease, box-shadow 0.2s ease;
&:hover {
color: #fff;
transform: translateY(-50%) translateX(-2px);
box-shadow: 0 10px 24px rgba(22, 119, 255, 0.4);
}
}
.online-service__icon {
font-size: 22px;
line-height: 1;
}
.online-service__text {
writing-mode: vertical-rl;
font-size: 14px;
line-height: 1.2;
letter-spacing: 2px;
}
@media (max-width: 768px) {
.online-service {
right: 12px;
padding: 10px 8px;
}
}
</style>七、界面精简与二次优化
原生uni-im页面带有官方侧边栏、多余功能入口，可根据需求精简：
进入项目uni-im/pages/index目录，通过审查元素定位无用模块，直接删除对应代码，移除官方广告、多余导航等无关内容，打造简洁的纯客服聊天界面。
八、项目打包上线与域名配置
本地测试无误后，将项目打包部署至云端正式使用：
- 项目发行：在HBuilder中选择发行Web端，勾选"编译后上传至网页托管"，选中对应的云服务空间，一键完成打包与云端部署。
- 同步云端代码：本地修改的配置、模块代码，需要重新上传公共模块与云函数，保证云端与本地代码一致。
- 域名替换：云端网页托管会提供默认域名，但默认域名有访问次数限制，正式商用务必绑定自有业务域名。在云服务后台完成域名解析与绑定，使用独立域名对外提供服务。
- 线上测试：使用自有域名拼接匿名聊天地址，测试访客匿名发消息、客服接收回复全流程，确认功能正常即完成整体搭建。
九、总结
使用uni-im搭建网站在线客服系统，依托开源优势大幅降低了开发与使用成本，整套流程分为环境准备、云端部署、本地配置、功能改造、打包上线五大环节。实操过程中，公共模块依赖导致的上传报错是主要难点，采用逐个手动上传的方式即可解决。
该框架扩展性极强，除了基础匿名客服功能，还可继续开发AI对话、消息记录、工单系统等功能。对于中小型网站、个人站点而言，uni-im完全可以替代高价商业化IM平台，是搭建轻量化在线客服的优质选择。