nim-web-sdk-ng

网易云信即时通讯 IM Elite SDK，为 web sdk 的下一代版本，提供完善的即时通信功能开发框架，屏蔽其内部复杂细节，对外提供较为简洁的 API 接口，方便第三方应用快速集成即时通信功能。

IM Elite SDK 分为 V1 和 V2 两个版本。V2 对 V1 的 API 接口做了大幅调整，并与其它客户端对齐。其中 V1 版本号 < 1，V2 版本号 >= 10。

安装

如果你是新用户，推荐使用 V2 API 的 SDK，安装方式为:

npm install nim-web-sdk-ng@">=10"

如果你是现有 V1 增强版用户，可使用下面命令安装 SDK。或者使用固定版本号安装

npm install nim-web-sdk-ng@"<1"

IM V2

sdk 选择

sdk 默认提供以下几种形式。其中 sdk 默认入口为 dist/v2/NIM_BROWSER_SDK.js。 注意，v2 暂未提供 QCHAT SDK。v2 IM SDK 接口兼容 v1 IM SDK。所以 v1 文件夹中没有构建 IM SDK。

dist/
  |── v2
    ├── NIM_BROWSER_SDK.js       v2 IM 浏览器适配版 UMD 格式
    ├── NIM_MINIAPP_SDK.js       v2 IM 小程序适配版 UMD 格式
    ├── NIM_UNIAPP_SDK.js        v2 IM UNIAPP 适配版 UMD 格式
    ├── NIM_RN_SDK.js            v2 IM RN 适配版 UMD 格式
    ├── CHATROOM_BROWSER_SDK.js  v2 聊天室浏览器适配版 UMD 格式
    ├── CHATROOM_MINIAPP_SDK.js  v2 聊天室小程序适配版 UMD 格式
    ├── CHATROOM_UNIAPP_SDK.js   v2 聊天室 UNIAPP 适配版 UMD 格式
    ├── CHATROOM_RN_SDK.js       v2 聊天室 RN 适配版 UMD 格式
  |── nodejs
    ├── nim.js                   v2 IM Node.js 适配版 ESM 格式
    ├── nim.d.ts                 TypeScript 类型定义入口
    ├── nim/                     TypeScript 类型定义目录
  |── v1
    ├── CHATROOM_BROWSER_SDK.js  v1 聊天室浏览器适配版 UMD 格式
    ├── CHATROOM_MINIAPP_SDK.js  v1 聊天室小程序适配版 UMD 格式
    ├── CHATROOM_UNIAPP_SDK.js   v1 聊天室 UNIAPP 适配版 UMD 格式
    ├── QCHAT_BROWSER_SDK.js     v1 圈组浏览器适配版 UMD 格式
    ├── QCHAT_UNIAPP_SDK.js      v1 圈组浏览器适配版 UMD 格式

基础引入例子

// 若使用 IM 能力则引入
import NIM from 'nim-web-sdk-ng'
// 等效于
import NIM from 'nim-web-sdk-ng/dist/v2/NIM_BROWSER_SDK'

// 0.11.0 版开始支持单例模式获取实例, 在此之前通过 new 创建实例
const nim = NIM.getInstance(
  {
    appkey: 'YOUR_APPKEY',
    debugLevel: 'debug',
    apiVersion: 'v2'
  },
  {}
)

nim.V2NIMLoginService.on('onLoginStatus', function (arg1) {
  console.log('收到 V2NIMLoginService 模块的 onLoginStatus 事件', arg1)
})

async function init() {
  try {
    await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN', {
      authType: 0
    })
  } catch (err) {
    console.error('login failed cause', err)
  }
}

init()

Node.js 环境

Node.js 版本专为服务端场景设计，支持在 Node.js 环境中使用 NIM SDK 的核心功能。

环境要求

• Node.js 版本: >= 20.0.0（使用原生 fetch、FormData、Blob API）
• 模块格式: ESM（ES Modules）
• 依赖: ws（WebSocket 库，已包含在 SDK 依赖中）

安装

npm install nim-web-sdk-ng@">=10"

引入方式

// Node.js 环境专用入口
import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'

支持的服务模块

服务模块	描述
V2NIMLoginService	登录服务
V2NIMMessageService	消息服务（发送/接收消息）
V2NIMMessageLogUtil	消息日志工具（查询历史消息）
V2NIMMessageExtendUtil	消息扩展工具（快捷评论、PIN 等）
V2NIMLocalConversationService	本地会话服务
V2NIMConversationService	会话服务
V2NIMConversationGroupService	会话分组服务
V2NIMUserService	用户服务
V2NIMFriendService	好友服务
V2NIMTeamService	群组服务
V2NIMNotificationService	通知服务
V2NIMStorageService	存储服务（文件上传下载）
V2NIMSettingService	设置服务
V2NIMSyncService	同步服务
V2NIMAIService	AI 服务
V2NIMSignallingService	信令服务
V2NIMPassthroughService	透传服务

基础示例

import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'

// 创建实例
const nim = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  debugLevel: 'debug',
  apiVersion: 'v2'
})

// 监听登录状态
nim.V2NIMLoginService.on('onLoginStatus', (status) => {
  console.log('登录状态:', status)
})

nim.V2NIMLoginService.on('onConnectStatus', (status) => {
  console.log('连接状态:', status)
})

// 登录
async function main() {
  try {
    await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN')
    console.log('登录成功')

    // 发送文本消息
    const message = nim.V2NIMMessageCreator.createTextMessage('Hello from Node.js!')
    const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')
    await nim.V2NIMMessageService.sendMessage(message, conversationId)
    console.log('消息发送成功')
  } catch (err) {
    console.error('操作失败:', err)
  }
}

main()

发送图片消息

import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'
import path from 'path'

const nim = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  apiVersion: 'v2'
})

async function sendImage() {
  await nim.V2NIMLoginService.login('YOUR_ACCOUNT', 'YOUR_TOKEN')

  // 使用文件路径创建图片消息
  const imagePath = path.join(process.cwd(), 'image.png')
  const message = nim.V2NIMMessageCreator.createImageMessage(imagePath, 'image.png')

  const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')

  // 发送消息，支持上传进度回调
  const result = await nim.V2NIMMessageService.sendMessage(message, conversationId, {}, (progress) => {
    console.log(`上传进度: ${Math.round(progress * 100)}%`)
  })

  console.log('图片发送成功:', result.attachment?.url)
}

sendImage()

查询历史消息

async function getHistory() {
  const conversationId = nim.V2NIMConversationIdUtil.p2pConversationId('TARGET_ACCOUNT')

  const messages = await nim.V2NIMMessageLogUtil.getMessageList({
    conversationId,
    limit: 50
  })

  messages.forEach((msg) => {
    console.log(`[${msg.senderId}]: ${msg.text || msg.messageType}`)
  })
}

TypeScript 支持

Node.js 版本提供完整的 TypeScript 类型定义：

import NIM from 'nim-web-sdk-ng/dist/nodejs/nim.js'
import type V2NIM from 'nim-web-sdk-ng/dist/nodejs/nim'

const nim: V2NIM = NIM.getInstance({
  appkey: 'YOUR_APPKEY',
  account: 'YOUR_ACCOUNT',
  token: 'YOUR_TOKEN',
  apiVersion: 'v2'
})

注意事项

1. 内存存储: Node.js 版本使用内存实现 localStorage，数据不会持久化。进程重启后会话和消息缓存将丢失。

2. 网络状态: 网络状态检测返回固定的"已连接"状态，不支持实时网络状态变化监听。

3. 电源状态: 电源状态相关 API 为存根实现，不提供实际功能。

4. 文件上传: 支持通过文件路径上传本地文件，使用原生 FormData 和 fetch API。

5. WebSocket: 使用 ws 库实现 WebSocket 连接，需确保网络环境允许 WebSocket 连接。

6. 长连接管理: 服务端场景建议实现心跳检测和断线重连逻辑，确保连接稳定性。

IM V1

sdk 选择

sdk 默认提供以下几种形式

dist/
├── CHATROOM_BROWSER_SDK.js  聊天室浏览器适配版 UMD 格式
├── CHATROOM_MINIAPP_SDK.js  聊天室小程序适配版 UMD 格式
├── CHATROOM_UNIAPP_SDK.js   聊天室 UNIAPP 适配版 UMD 格式
├── NIM_BROWSER_SDK.js       IM 浏览器适配版 UMD 格式
├── NIM_MINIAPP_SDK.js       IM 小程序适配版 UMD 格式
├── NIM_UNIAPP_SDK.js        IM UNIAPP 适配版 UMD 格式
├── QCHAT_BROWSER_SDK.js     圈组浏览器适配版 UMD 格式

基础引入例子

// 若使用 IM 能力则引入
import NIM from 'nim-web-sdk-ng'
// 等效于
import NIM from 'nim-web-sdk-ng/dist/NIM_BROWSER_SDK'

// 0.11.0 版开始支持单例模式获取实例, 在此之前通过 new 创建实例
const nim = NIM.getInstance(
  {
    debugLevel: 'debug',
    appkey: 'YOUR_APPKEY',
    account: 'YOUR_ACCOUNT',
    token: 'YOUR_TOKEN'
  },
  {}
)

async function init() {
  try {
    if (nim.status === 'unconnected' || nim.status === 'waitReconnect') {
      await nim.connect()
    }
  } catch (err) {
    console.error('login failed cause', err)
  }
}

init()