网易云信 IM SDK（NetEase Instant Messaging SDK，简称 NIM SDK）为开发者提供完善的即时通讯能力，精心屏蔽底层复杂实现细节，对外呈现简洁易用的 API，助您轻松快速地将即时通讯功能整合到应用中。

uni-app x 是下一代 uni-app，是一个跨平台应用开发引擎。支持 Android、iOS、鸿蒙、web、微信小程序。

uts 全称 uni type script，是一门跨平台的、高性能的、强类型的现代编程语言。它在不同平台，会被编译为不同平台的native语言。uts 语言的主要作用是开发 uts 原生插件。

本文介绍如何快速将 NIM uni-app x SDK 集成到您的项目中，开启高效通讯体验。

功能模块

NIM uni-app x SDK 底层依赖原生 SDK（v10.10.10），支持同时编译至 Android、iOS、HarmonyOS 客户端。目前已开放的功能模块如下：

服务	说明
V2NIMLoginService	登录、登出、连接状态、监听
V2NIMUserService	用户资料、黑名单、好友
V2NIMFriendService	好友关系管理
V2NIMMessageService	消息收发、查询、撤回、删除
V2NIMMessageCreate	构造文本/图片/语音等消息
V2NIMMessageConvert	消息序列化与反序列化
V2NIMConversationService	会话列表、未读、置顶
V2NIMLocalConversationService	本地会话管理
V2NIMConversationGroupService	会话分组
V2NIMConversationIdUtils	会话 ID 生成与解析（原生 SDK 类名为 V2NIMConversationIdUtil，uni-app x 层统一加 s，具体请参考 命名差异。）
V2NIMTeamService	群与超级群
V2NIMStorageService	云端存储
V2NIMSettingService	用户设置
V2NIMSubscriptionService	在线状态订阅
V2NIMStatisticsService	统计上报
V2NIMPassthroughService	透传
V2NIMNotificationService	通知

开发环境

NIM uni-app x SDK 支持以下开发环境：

• Android 7.0 及以上版本。
• iOS 13 及以上版本。
• HarmonyOS 17 及以上版本。

集成

通过 HBuilderX 插件市场 安装插件。安装后，插件文件位于 uni_modules/nim-uts-sdk/，引用路径为 @/uni_modules/nim-uts-sdk。

三端原生 SDK 依赖由各平台 utssdk/<platform>/config.json 声明，编译时自动合并至 Gradle/Podfile/oh-package.json5，无需手动修改原生工程。

初始化与登录

集成 SDK 后，需先完成 NIM 实例的初始化方可使用其他功能。

1. 通过 new <Service>() 获取各服务实例。
2. 按平台构造 SDKOptions（仅 appKey 为必填）。
3. 调用 initNIMSDK 初始化 SDK。
4. 创建 V2NIMLoginService 实例并调用 login 登录。

示例代码：

Typescriptimport {
  initNIMSDK,
  NIMInitSuccess,
  NIMFail,
  V2NIMLoginService,
  V2NIMLoginListener,
  V2NIMDataSyncLevel
} from '@/uni_modules/nim-uts-sdk'

// #ifdef APP-ANDROID
import { AndroidSDKOptions } from '@/uni_modules/nim-uts-sdk'
// #endif
// #ifdef APP-HARMONY
import { HarmonySDKOptions } from '@/uni_modules/nim-uts-sdk'
// #endif

const APP_KEY = 'your_app_key'
const ACCOUNT_ID = 'your_accid'
const TOKEN = 'your_token'

// 1. 按平台构造 SDKOptions（仅 appKey 是必填，其余字段按需设置）
// #ifdef APP-ANDROID
const sdkOptions = new AndroidSDKOptions()
// #endif
// #ifdef APP-HARMONY
const sdkOptions = new HarmonySDKOptions()
// #endif
// #ifdef APP-IOS
const sdkOptions = { appKey: APP_KEY }
// #endif
sdkOptions.appKey = APP_KEY

// 2. 初始化 SDK
initNIMSDK({
  options: sdkOptions,
  success(res: NIMInitSuccess) {
    console.log('init ok', res)
  },
  fail(err: NIMFail) {
    console.error('init fail', err)
  }
})

// 3. 登录
const loginService = new V2NIMLoginService()

loginService.addLoginListener({
  onLoginStatus(status) {
    console.log('login status', status)
  },
  onLoginFailed(error) {
    console.error('login failed callback', error)
  }
} as V2NIMLoginListener)

loginService.login(ACCOUNT_ID, TOKEN, {
  syncLevel: V2NIMDataSyncLevel.V2NIM_DATA_SYNC_TYPE_LEVEL_FULL
}).then((res) => {
  if (res.code == 200) {
    console.log('login ok', res.data)
  } else {
    console.error('login fail', res)
  }
})

三端 login 均返回 Promise<NIMResult<T>>，业务侧按 res.code == 200 判定成功，res.data 获取结果。iOS 端 V2NIMLoginAuthType 暂未桥接导出，登录 option 目前仅需填写 syncLevel。

API 参考

uni-app x 层是对原生 V10 SDK 的桥接封装，方法签名与语义以原生 SDK 为准。如遇字段含义、取值枚举、回调时序等问题，请参考 原生 SDK API。

更多参考

命名差异

三端原生 SDK 中会话 ID 工具类名为 V2NIMConversationIdUtil（单数）。为与 uni-app x 层「工具类使用复数」的命名约定保持一致（参考 V2NIMMessageCreator/V2NIMMessageConverter），本插件统一导出为 V2NIMConversationIdUtils（带 s）。

Typescript// 正确用法
import { V2NIMConversationIdUtils } from '@/uni_modules/nim-uts-sdk'
const util = new V2NIMConversationIdUtils()
util.p2pConversationId(accountId)

调用方法与原生 V2NIMConversationIdUtil 完全一致（p2pConversationId/teamConversationId/superTeamConversationId/conversationType/conversationTargetId/isConversationIdValid 等），仅类名增加 s。

升级原生 SDK

原生 SDK 版本号分别声明在三端各自的 config.json 中，升级时需同步修改以下三处：

平台	文件路径	修改位置
Android	utssdk/app-android/config.json	dependencies 数组中的 com.netease.nimlib:basesdk:<version> 和 com.netease.nimlib:chatroom:<version>
iOS	utssdk/app-ios/config.json	dependencies-pods 中 NIMSDK_LITE 的 version
HarmonyOS	utssdk/app-harmony/config.json	dependencies 对象中的 @nimsdk/* 版本号

升级示例（V10.10.10 → V10.11.0）：

// utssdk/app-android/config.json
- "com.netease.nimlib:basesdk:10.10.10",
- "com.netease.nimlib:chatroom:10.10.10"
+ "com.netease.nimlib:basesdk:10.11.0",
+ "com.netease.nimlib:chatroom:10.11.0"

// utssdk/app-ios/config.json
- "version": "10.10.10"
+ "version": "10.11.0"

// utssdk/app-harmony/config.json
- "@nimsdk/nim": "10.10.10",
- "@nimsdk/base": "10.10.10",
+ "@nimsdk/nim": "10.11.0",
+ "@nimsdk/base": "10.11.0",
  ...（其余 @nimsdk/* 同步改）

• 三端 必须 升级至同一原生 SDK 版本，避免跨端行为不一致。
• 升级后建议同步更新 changelog.md 记录版本变更。
• 若新版本引入新的初始化字段或 API，需同步修改 utssdk/<platform>/ 下对应的 Service/Options 文件，补充桥接字段后方可在 uni-app x 层使用。
• utssdk/types/CrossPlatformMeta.uts 中的 CROSS_PLATFORM_VERSION 为跨端技术栈版本号，与原生 SDK 版本无关，请勿混淆。

跨端版本标记维护

uni-app x 层向原生 SDK 透传的「跨端技术栈种类」与「跨端技术栈版本号」统一由 utssdk/types/CrossPlatformMeta.uts 控制：

常量	说明	当前值
CROSS_PLATFORM_TYPE	跨端技术栈种类（112 对应 uni-app-x）	112
CROSS_PLATFORM_VERSION	跨端技术栈版本号	'1.0.0'

Android、iOS、HarmonyOS 三端的初始化脚本均 import 该文件，并将值赋给原生 SDK 初始化配置。升级或调整跨端标记时，仅需修改此文件中的两行常量，三端自动生效。

• crossPlatformType 不再承载于 package.json，uni-app x 运行时无法读取 package.json，因此 CrossPlatformMeta.uts 为唯一来源。
• package.json 中的 version 为插件自身版本，与 CROSS_PLATFORM_VERSION 为两个独立概念，无需强制同步。