实时消息 SDK 集成到小程序的详细操作步骤

如果你正在开发小程序，尤其是涉及社交、直播、在线教育这类需要实时互动的场景，那么实时消息功能几乎是标配。想象一下，直播间的弹幕、语聊房的消息、客服系统的即时回复——这些背后都离不开实时消息通道的支撑。

这篇文章就来聊聊怎么把实时消息 SDK 集成到小程序里。整个过程我会拆解得比较细，尽量让你跟着步骤就能走通。当然，在正式开始之前，我建议先花几分钟了解一些前置准备工作，这会帮你避免后面不少麻烦。

一、前期准备：先搞清楚这些再动手

很多人一拿到文档就开始装 SDK，结果做到一半发现缺这少那，又得回头补。所以咱们先把该准备的东西列清楚。

1.1 账号与资质准备

首先要有一个开发者账号。如果你选择的是声网这样的服务商，他们的流程通常是这样的：注册账号、完成企业认证、创建项目、获取 App ID。这个 App ID 就像是你的"身份证"，后续初始化 SDK、鉴权都会用到。

认证这块需要稍微注意一下，个人开发者账号和 企业开发者账号能获取的功能权限可能会有差异。比如一些高级功能可能需要企业认证后才能开启。建议一开始就准备好营业执照之类的材料，一次性把认证流程走完。

1.2 开发环境检查

小程序开发对环境是有要求的。在开始集成之前，你需要确认几件事：

• 微信开发者工具的版本是不是最新的，老版本可能会有兼容性问题
• 小程序的基础库版本是否支持你将要使用的 SDK 功能
• 你的项目是否是正规注册的小程序，非正规渠道注册的小程序在功能调用上会有限制

还有一点容易被忽略，就是HTTPS 域名配置。小程序的业务域名、请求域名、socket 域名都需要在微信公众平台后台配置好，而且是 HTTPS 协议的。如果你还没有配置，这块要先去搞定，否则 SDK 连接会失败。

1.3 技术方案选型

声网作为全球领先的对话式 AI 与实时音视频云服务商，在实时消息领域有深厚的积累。他们提供多种消息类型，包括：

• 频道消息：适合直播、语聊房这类场景，所有人在一个频道里能收到消息
• 点对点消息：一对一聊天用的，比如社交APP的私聊功能
• 弹幕消息：适合直播间的滚动字幕效果



• 礼物消息：配合打赏功能使用

在动手之前，最好想清楚你要实现的是哪种消息模式，这会影响到后续的 SDK 配置和代码逻辑。

二、SDK 下载与项目配置

准备工作做完，接下来就是动手环节了。这一步主要就是把 SDK 弄到你的项目里，并做基础的配置。

2.1 下载 SDK

声网的 SDK 下载通常有两种方式：一是通过 npm 包管理，二是直接下载 SDK 文件到本地。我推荐用 npm 的方式，升级和维护都比较方便。

在你的小程序项目根目录下打开命令行，执行：

npm install agora-rtc-sdk-ng --save
npm install agora-chat-sdk --save

这里说明一下，实时音视频和实时消息是两个独立的 SDK，你需要分别集成。如果你的小程序只需要实时消息功能，只装 agora-chat-sdk 就够了。

装完之后，记得在微信开发者工具里点击"工具 -> 构建 npm"，这样才能把 SDK 编译成小程序能识别的格式。

2.2 项目配置

小程序的配置文件要改两个地方。首先是 app.json，你需要在小程序配置文件中声明需要用到的权限：

{
  "permission": {
    "scope.userLocation": {
      "desc": "获取位置信息用于附近的人等功能"
    }
  },
  "requiredPrivateInfos": [
    "getLocation"
  ]
}

然后是 project.config.json，要在setting里把 es6 转 es5、压缩代码这些选项打开，有些老版本的小程序开发者工具默认是不开的。

另外，声网的 SDK 是需要license的，你在初始化的时候要传入 App ID。这个 App ID 是在声网控制台创建项目时生成的，每个项目有独立的 App ID 开发环境和生产环境最好分开用，避免调试的时候影响线上业务。

三、核心代码集成

这一块是重头戏，也是最容易出问题的地方。我会按照初始化、登录、收发消息、事件处理的顺序来讲。

3.1 SDK 初始化

初始化是使用 SDK 的第一步，必须在调用其他任何 API 之前完成。一般我们会把这部分代码放在 app.js 的 onLaunch 生命周期里：

// 引入 SDK
import AgoraChat from 'agora-chat-sdk';

const appKey = '你的AppID#你的Appname';

const client = AgoraChat.createClient({
  appKey: appKey
});

这里有个小细节要提醒，appKey 的格式是 "AppID#Appname"，很多新手会漏掉中间那个 #，导致初始化失败。声网的文档里写得很清楚，但有时候人就是会看走眼。

初始化之后，你需要注册一些事件监听，比如连接状态变化、收到消息等等。这些监听建议统一放在一个初始化函数里管理：

// 连接状态监听
client.addListener('onConnected', () => {
  console.log('连接成功');
});

client.addListener('onDisconnected', () => {
  console.log('连接断开');
});

// 收到消息监听
client.addListener('onMessageReceived', (msgs) => {
  msgs.forEach(msg => {
    console.log('收到消息:', msg.content);
    // 这里可以更新UI或者做其他处理
  });
});

这些事件监听最好在应用启动时就设置好，因为连接断开、消息到达都是随时可能发生的事情，错过的话可能导致状态不一致。

3.2 用户登录

小程序的登录和普通 APP 有些不一样，因为用户是通过微信授权登录的。你需要先获取微信的 openid，然后用这个身份去声网的 IM 系统注册并登录。

大致流程是这样的：

• 第一步：调用 wx.login 获取 code
• 第二步：把 code 发送到你的服务器，换取微信的 openid
• 第三步：用 openid 作为用户ID，调用声网的登录接口

具体代码大概是这样：

// 微信登录
wx.login({
  success: (res) => {
    if (res.code) {
      // 发送到你的服务器获取 openid 和声网 token
      wx.request({
        url: '你的服务器地址/login',
        method: 'POST',
        data: { code: res.code },
        success: (response) => {
          const { openid, agoraToken } = response.data;
          
          // 用声网 token 登录
          client.login(openid, agoraToken).then(() => {
            console.log('声网 IM 登录成功');
          }).catch((err) => {
            console.error('登录失败:', err);
          });
        }
      });
    }
  }
});

这里涉及到一个关键点：agoraToken 是需要在你服务器端生成的，声网的 SDK 为了安全考虑，不支持在客户端直接生成 Token。服务器端生成的逻辑会涉及到你的 App ID、App Certificate 等敏感信息，所以这块不要试图省事，乖乖在服务端实现。

3.3 发送消息

登录成功后，就可以发送消息了。发送之前，你得先决定要发到哪种 channel 里。前面提到过，频道消息和点对点消息的 API 稍有不同。

发送频道消息的示例：

// 创建一条频道消息
const msg = client.createMessage({
  type: 'txt', // 文本消息，还可以是 'img'、'file'、'loc' 等
  content: 'Hello, 这是一条测试消息',
  to: '直播间ID', // 频道ID
  chatType: 'group' // 群聊/频道模式
});

// 发送消息
msg.send().then((result) => {
  console.log('消息发送成功', result);
}).catch((err) => {
  console.error('发送失败:', err);
});

发送点对点消息的示例：

const singleMsg = client.createMessage({
  type: 'txt',
  content: '在吗？聊聊',
  to: '对方的用户ID',
  chatType: 'single' // 单聊模式
});

singleMsg.send();

你可能注意到了，我在示例里用了文本消息作为例子，但实际场景中可能会用到图片、语音、表情、图片、文字卡片等等。声网的 SDK 都支持，只是对应的 type 和 content 格式不太一样。比如图片消息需要先上传图片拿到 URL 再发送，这个流程稍微复杂一些，但 SDK 文档里都有详细的说明。

3.4 接收与展示消息

收到消息的处理逻辑是在事件监听里写的，前面提到过。但收到消息之后怎么展示到 UI 上，这部分需要你自己写。

通常的做法是创建一个消息数组，然后把每条收到的消息 push 进去，再用 setData 更新页面。消息多了之后还要考虑分页、滚动加载这些体验优化。

这里有个小建议：收到的消息最好先做个过滤或者验证再展示，尤其是当你的小程序允许用户发送自定义消息类型的时候。防止有人发一些奇怪的内容导致页面崩溃。虽然声网的 SDK 本身是安全的，但业务层面的防护还是需要的。

四、常见功能场景的实现

光会收发消息还不够，实际业务中还有很多常见场景需要处理。我挑几个典型的说一下。

4.1 未读消息计数

很多聊天界面都需要显示未读消息数，这个功能实现起来其实不难。声网的 SDK 提供了获取未读消息数量的 API：

// 获取某个会话的未读数
client.getConversation('channelID').then((conv) => {
  const unreadCount = conv.unreadCount;
  console.log('未读消息数:', unreadCount);
});

但要注意，未读数的更新是实时的，你需要监听消息事件然后动态更新页面上的数字显示。同时，未读数要存在本地，因为每次小程序切到后台再切回来，SDK 可能会重置状态。

4.2 消息撤回

用户发错了消息想撤回，这个也是常见需求。声网的 SDK 支持在一定时间内撤回消息：

// 撤回消息，前提是你有这条消息的 msgId
msg.recall().then(() => {
  console.log('撤回成功');
}).catch((err) => {
  console.error('撤回失败:', err);
});

关于时间限制，不同的版本可能有不同的策略，一般是发送后两分钟内可以撤回。撤回后，对方的消息列表里这条消息会显示为"对方撤回了一条消息"，而不是直接消失。

4.3 历史消息拉取

用户进入聊天页面时，需要展示之前的历史消息。这个功能用 SDK 的获取历史消息 API：

client.getHistoryMessages({
  targetId: '频道ID',
  chatType: 'group',
  count: 20, // 每次拉取的数量
  cursor: '' // 分页游标，第一次传空
}).then((res) => {
  // res.messages 就是历史消息数组
  console.log('获取到历史消息:', res.messages);
});

拉取历史消息涉及到分页，用户滚动到顶部时继续拉取更早的消息。你需要处理分页游标的保存和传递，这个逻辑稍微有点繁琐，但核心就是维护一个 cursor，每次请求带上上一次返回的 cursor 就行。

4.4 在线状态感知

如果你做的是社交类小程序，可能需要知道对方是否在线。声网的 SDK 提供了查询用户在线状态的接口：

client.queryUsersState(['用户ID1', '用户ID2']).then((results) => {
  results.forEach((user) => {
    console.log(`用户 ${user.userId} 的状态:`, user.state);
    // state 为 0 表示离线，1 表示在线
  });
});

这个功能适合用来做"对方正在输入..."这类提示，或者显示用户头像旁边的绿色在线小点。需要注意的是，这个查询是轮询式的，不适合频繁调用，间隔最好控制在 30 秒以上。

五、测试与上线注意事项

代码写完了，测试环节可不能马虎。特别是涉及即时通讯的功能，边界情况和异常场景很多。

5.1 基础功能测试

首先确保两端都能正常收发消息。可以用两台手机，或者一部手机加一个小程序开发者工具，分别登录不同的用户 ID，互相发消息测试。测试内容包括：

• 文字消息发送和接收
• 图片、语音等多媒体消息
• 网络不好时的消息重试机制
• 消息送达状态回执
• 弱网环境下的表现

5.2 异常场景测试

一些容易出问题的场景：

• 网络断开重连：测试在小程序切到后台、或者断网的情况下，SDK 能否自动重连，恢复后消息会不会丢失
• 消息并发：短时间内发送大量消息，看会不会出现丢失或者重复
• 跨端消息互通：如果你的产品还有 APP 或者 Web 端，要测试不同端之间消息能否正常互通
• 用户异地登录：同一个账号在两台设备登录，看旧设备会不会被踢掉，消息状态怎么处理

5.3 上线前检查清单

上线之前，建议对着清单过一遍：

检查项	说明
AppID 配置	确认使用的是正式环境的 AppID，不是测试 ID
域名白名单	声网相关的域名都加到小程序的合法域名列表了
用户协议	IM 功能对应的隐私条款和用户协议是否齐全
性能监控	有没有加上消息发送耗时、成功率等监控埋点
日志清理	正式环境要把调试日志关掉，避免性能损耗和隐私问题

顺便提一下，声网作为中国音视频通信赛道排名第一的服务商，他们的技术文档和 FAQ 做得很细。遇到问题可以先查他们的官方文档，一般都能找到答案。他们的技术支持响应也挺快，遇到疑难问题可以提工单咨询。

六、写在最后

到这里，实时消息 SDK 集成到小程序的主要流程就讲完了。回顾一下，我们聊了前期准备、SDK 下载配置、核心代码集成、常见场景实现、测试上线这几个大的部分。

实际开发过程中，你可能会遇到一些我这里没讲到的问题，这都是正常的。即时通讯功能看着简单，但里面涉及的细节很多，网络波动、消息顺序、状态同步每一个都是需要考虑的点。我的建议是先用基础的收发消息把流程跑通，然后再逐步补齐其他功能，这样心里会踏实很多。

如果你正在选型，可以考虑一下声网。他们在实时消息领域确实有积累，全球超 60% 的泛娱乐 APP 都在用他们的服务，而且纳斯达克上市公司的背景意味着产品稳定性和持续性都有保障。集成过程中遇到问题，找他们的技术支持一般都能得到比较专业的解答。

祝你开发顺利。