环信 Web IM SDK

easemob-websdk 是面向 Web 应用的 TypeScript IM SDK，提供连接管理、消息、会话、联系人、群组、聊天室、用户资料、在线状态和推送设置等类型安全的 API。

安装

npm install easemob-websdk

发布包同时支持 ESM 和 CommonJS。可从主入口导入完整 SDK，也可从 Manager 子路径导入，以便业务构建工具移除未使用的 Manager 代码。

快速开始

使用应用所需的 Manager 初始化客户端，再使用由应用服务端签发的用户 Token 登录：

import { ChatClient, ChatManager } from 'easemob-websdk';

const client = ChatClient.init({
  appKey: 'your-org#your-app',
  managers: [ChatManager],
});

client.addEventHandler('connection', {
  onConnected: () => {
    console.log('connected');
  },
  onDisconnected: event => {
    console.warn('disconnected', event.reason);
  },
});

await client.login({
  userId: 'user-id',
  token: 'user-token',
});

登录成功后可发送单聊文本消息：

const message = client.chatManager.createTextMessage({
  conversationId: 'peer-user-id',
  conversationType: 'singleChat',
  content: 'Hello from Easemob',
});

await client.chatManager.sendMessage(message);

Manager 子路径导入

import { ChatClient } from 'easemob-websdk';
import { ChatManager } from 'easemob-websdk/managers/chat';
import { GroupManager } from 'easemob-websdk/managers/group';

const client = ChatClient.init({
  appKey: 'your-org#your-app',
  managers: [ChatManager, GroupManager],
});

可用的 Manager 子路径：

• easemob-websdk/managers/chat
• easemob-websdk/managers/chat-thread
• easemob-websdk/managers/chatroom
• easemob-websdk/managers/contact
• easemob-websdk/managers/group
• easemob-websdk/managers/presence
• easemob-websdk/managers/push
• easemob-websdk/managers/user-info

浏览器 script 标签

未使用打包工具的 Web 应用可从 CDN 加载 IIFE bundle，加载后的全局变量为 IMSDK：

<script src="https://unpkg.com/easemob-websdk@latest/bundle/im-sdk-web.iife.js"></script>
<script>
  const client = IMSDK.ChatClient.init({
    appKey: 'your-org#your-app',
    managers: [IMSDK.ChatManager],
  });
</script>

错误处理

所有公开异步 API 都会 reject SDKError 子类。请根据稳定的 SDK 错误码处理异常，不要解析错误文案：

import { isSDKError } from 'easemob-websdk';

try {
  await client.login({ userId: 'user-id', token: 'user-token' });
} catch (error) {
  if (isSDKError(error)) {
    console.error(error.code, error.message, error.details);
  }
}

安全建议

• 从应用服务端获取用户 Token，不要把 App 凭据或长期有效 Token 写入浏览器代码。
• 不要在业务日志中输出 Token、授权请求头或消息正文。
• 按照应用自身的安全策略保存和刷新 Token。

资源

• 官网：https://www.easemob.com/
• SDK 发布文档提供生成的 TypeDoc API Reference 与错误码表。