网易云信 IM SDK（NetEase Instant Messaging SDK，简称 NIM SDK）为 Web 应用开发者提供完善的即时通信功能开发能力，屏蔽其内部复杂细节，对外提供较为简洁的 API，方便您快速集成即时通信功能。

本文介绍如何快速将 NIM SDK 集成到您的 Web 项目中。

环境适配

NIM SDK 支持以下开发环境：

• 微软 IE（10+）
• 谷歌 Chrome（7+）
• 微软 Edge（12+）
• Mozilla Firefox（11＋）
• 苹果 Safari（5+）
• DCloud uni-app
• 微信/支付宝/百度/抖音小程序

域名配置

对于小程序项目而言（包括最终编译为小程序应用的 uni-app 项目），在开始集成前，请确保您：

• 已在 微信公众平台 中进入 小程序后台 > 开发 > 开发设置 > 服务器域名，将以下域名填入指定的 request 合法域名、socket 合法域名、uploadFile 合法域名、downloadFile 合法域名 中。更多相关说明，请参考《微信官方文档》配置服务器域名。

• 如果您需要在支付宝运行小程序，请在 支付宝开放平台 对应路径配置服务器域名。

  配置分类	域名	说明
  request 合法域名	https://lbs.netease.im/lbs/wxwebconf.jsp	请求 LBS（Location Based Services）地址。微信小程序必须使用的地址。
  	https://lbs.netease.im	请求 LBS 地址。
  	https://wlnimsc0.netease.im	IM 必需。
  	https://wlnimsc0.netease.im:443	IM 必需。
  	https://wlnimsc1.netease.im	聊天室必需。
  	https://wlnimsc1.netease.im:443	聊天室必需。
  	https://statistic.live.126.net	数据上报。
  	https://abt-online.netease.im	用于 A/B Test。
  socket 合法域名	wss://wlnimsc0.netease.im	IM 必需。
  	wss://wlnimsc1.netease.im	聊天室必需。
  uploadFile 合法域名	https://oss.chatnos.com	文件上传，如发送文件类消息。
  	https://fileup.chatnos.com
  	https://nos.netease.com
  downloadFile 合法域名	https://nim-nosdn.netease.im	文件下载，如下载语音。
  	https://nim.nosdn.127.net

方式一：正常集成

以下步骤适用于 Web、uni-app、小程序应用：

1. 通过如下 npm 命令安装最新版 SDK。

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

2. 通过 import 或者 require 引入入口模块。根据开发环境不同，您应该选择不同的产物。目前产物包括：

   业务场景	需引入的模块	初始化方法
   IM 浏览器	NIM_BROWSER_SDK	NIM.getInstance
   IM UniApp	NIM_UNIAPP_SDK	NIM.getInstance
   IM 小程序	NIM_MINIAPP_SDK	NIM.getInstance
   Chatroom 浏览器	CHATROOM_BROWSER_SDK	CHATROOM.newInstance
   Chatroom UniApp	CHATROOM_UNIAPP_SDK	CHATROOM.newInstance
   Chatroom 小程序	CHATROOM_MINIAPP_SDK	CHATROOM.newInstance

   • 若开发环境为浏览器，您应该按照下面的路径引入：

     TypeScript// 引入方式一：引入默认路径
     import NIM from 'nim-web-sdk-ng'
     // 引入方式二：指定引入路径。该路径等效于默认路径
     import NIM from 'nim-web-sdk-ng/dist/v2/NIM_BROWSER_SDK'
     

   • 若开发环境为 uni-app，您应该按照下面的路径引入:

     TypeScriptimport NIM from 'nim-web-sdk-ng/dist/v2/NIM_UNIAPP_SDK'
     

   • 若开发环境为小程序，由于小程序构建 npm 之后，只有默认路径文件才会被复制到 miniprogram_npm 中，而 IM SDK 小程序包不是默认路径。因此，您需要将 nim-web-sdk-ng/dist/v2 拷贝到项目的其它目录中，然后引入:

     TypeScriptimport NIM from '{相对路径}/NIM_MINIAPP_SDK'
     

方式二：ESM 引入

NIM SDK 默认导出 UMD（Universal Module Definition）格式的产物，这种格式的文件可以在多种环境中使用。当应用对包体积有更严格的要求，例如小程序应用，则可以使用 ESM（ECMAScript Module）格式的 SDK。ESM 是 JavaScript 的原生模块系统，允许更细粒度的模块控制和更有效的打包。再配合 webpack 实现 tree-shaking（一种去除代码中未引用部分的方式），从而进一步降低 NIM SDK 产物体积。

下载 NIM SDK 后，ESM 产物路径在 nim-web-sdk-ng/dist/esm/nim.js 中。截至 10.5.0 NIM SDK，ESM 产物导出了所有 V2NIM 模块，共有 550kb，只引入消息与会话有关的功能模块则约为 400kb。

完整示例

有关 ESM 引入并集成的完整示例请参考以下文件：

• Web 浏览器示例：browser.zip
• uni-app 示例：uniApp.zip
• 微信小程序示例：wxMiniApp.zip

引入步骤

1. 通过 ESM 方式引入 NIM SDK 时，您需要根据目标运行环境（例如 uni-app、浏览器、微信小程序等）手动选择相应的适配器代码，以确保 NIM SDK 能在不同环境中正确运行：

   • uniAppAdapters：为 uni-app 框架准备的适配器。uni-app 是一个使用 Vue.js 开发跨平台应用的前端框架，可以编译到 iOS、Android、Web（包括 PC 和移动端）、以及各种小程序（微信/支付宝/百度等）平台。
   • browserAdapters：为浏览器环境准备的适配器。如果您的代码需要在浏览器中运行，可能需要一些特定的适配代码来处理不同浏览器之间的兼容性问题。
   • wxAdapters：为微信小程序准备的适配器。
   • aliAdapters：为支付宝小程序准备的适配器。
   • baiduAdapters：为百度小程序准备的适配器。
   • ttAdapters：为抖音小程序准备的适配器。

2. 您需要调用 registerService 注册所需模块，以及环境变量。可供注册的模块如下：

   • V2NIMConversationService：会话模块。
   • V2NIMConversationGroupService：会话分组模块。
   • V2NIMMessageService：消息模块。包含发送消息等功能。
   • V2NIMMessageLogUtil：消息模块-消息记录相关工具类。包含查询消息历史等功能。
   • V2NIMMessageExtendUtil：消息模块-扩展功能。包含 pin 消息，收藏消息等功能。
   • V2NIMMessageConverter：消息模块-消息序列化能力。
   • V2NIMStorageService：云端存储模块，包含上传文件能力。
   • V2NIMTeamService：群组模块。
   • V2NIMUserService：用户模块。
   • V2NIMFriendService：好友模块。
   • V2NIMNotificationService：通知模块服务。
   • V2NIMSettingService：设置模块。包含推送配置，会话免打扰设置等。
   • V2NIMAIService AI：数字人模块。
   • V2NIMSignallingService：信令模块。
   • V2NIMSubscriptionService：订阅模块，如上下线状态通知订阅。
   • V2NIMPassthroughService：服务代理相关。

3. 某些模块包含工具类，您只需要引入对应模块服务，就能直接使用该工具类。关系如下：

   • V2NIMConversationIdUtil：会话 ID 工具类。被 V2NIMMessageService 和 V2NIMConversationService 包含。
   • V2NIMMessageAttachmentCreator：消息附件构造工具类。被 V2NIMMessageService 包含。
   • V2NIMClientAntispamUtil：客户端反垃圾工具类。被 V2NIMMessageService 包含。
   • V2NIMMessageCreator：消息构造工具类。被 V2NIMMessageService 包含。

   引入代码讲解：

   JavaScript/** lib.js */
   import { NIM, setAdapters, browserAdapters, V2NIMMessageService, V2NIMConversationService, V2NIMConst } from 'nim-web-sdk-ng/dist/esm/nim'
   
   // 1. ESM 模式需要手动指明需要安装哪个环境适配器。以下设置浏览器环境的适配器。
   setAdapters(browserAdapters)
   
   // 2. ESM 模式需要指明有哪些 SDK 模块需要注册。以下注册了消息服务和会话服务
   NIM.registerService(V2NIMMessageService, 'V2NIMMessageService')
   NIM.registerService(V2NIMConversationService, 'V2NIMConversationService')
   
   // 3. 导出 NIM 类, 与 V2NIM 相关的常量.
   export { NIM, V2NIMConst }
   

4. 引入上文的 lib.js，具体初始化使用见下文代码：

   JavaScriptimport { NIM, V2NIMConst } from './lib'
   
   const nim = NIM.getInstance({
     appkey: 'YOUR_APPKEY',
     debugLevel: 'debug',
     apiVersion: 'v2'
   })
   
   // ...
   // 本节介绍 ESM 引入和集成，略去其他登录细节。
   

初始化实例

将 NIM SDK 集成到客户端后，您需要先完成 NIM 实例的初始化才能使用其他功能。

本文主要介绍 NIM_BROWSER_SDK 的初始化。示例代码如下：

• 浏览器环境，及运行在非小程序的 uni-app 环境，使用下面方式初始化：

  TypeScriptconst nim = NIM.getInstance({
      appkey: "YOUR_APPKEY",
      debugLevel: "debug",
      apiVersion: "v2"
  })
  

• 小程序环境，及运行在小程序的 uni-app 环境，使用下面方式初始化。之所以小程序需要和非小程序区分，是因为小程序需要设置域名白名单，因此需要返回固定域名的 lbs 请求地址。

  TypeScriptconst nim = NIM.getInstance({
      appkey: "YOUR_APPKEY",
      debugLevel: "debug",
      apiVersion: "v2"
  }, {
  V2NIMLoginServiceConfig: {
      "lbsUrls": [
      "https://lbs.netease.im/lbs/wxwebconf.jsp"
      ],
      "linkUrl": "wlnimsc0.netease.im"
  }
  })
  

• 下面代码演示如何登录，以及通过 onLoginStatus 事件来监听登录状态变化。

  TypeScriptnim.V2NIMLoginService.on('onLoginStatus', function(arg1) {
  console.log('收到 V2NIMLoginService 模块的 onLoginStatus 事件', arg1)
  })
  await nim.V2NIMLoginService.login("YOUR_ACCOUNT", "YOUR_TOKEN")
  

• 登录后，发送点对点消息。

  TypeScriptconst message = nim.V2NIMMessageCreator.createTextMessage("hello")
  const res = await nim.V2NIMMessageService.sendMessage(message, 'YOUR_ACCOUNT|1|RECEIVER_ACCOUNT')
  

下一步

完成 SDK 集成后，请参考 初始化 和 登录 IM 进行集成开发。