集成 Flutter SDK - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

集成 Flutter SDK

更新时间： 2026/03/31 18:08:13

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

目前网易云信支持 Flutter 全平台（Android、iOS、MacOS、Windows、Web）的即时通讯 IM SDK，帮助您一套代码，全平台运行。本文介绍如何快速将 NIM Flutter SDK 集成到您的项目中。

本文主要介绍底层 Flutter SDK 的集成，若您需要集成对应的 UI 组件，请参考集成 Flutter UIKit。

环境要求

集成 NIM Flutter SDK 前，请确保您的本地开发环境满足以下要求：

Dart SDK 版本：3.4.0 ~ 4.0.0
Flutter SDK 版本 ：3.22.0 及以上版本

项目开发环境：

Android	iOS	macOS	Windows	Web	鸿蒙
Android Studio 3.5 及以上版本 Android 5.0 及以上版本设备 Kotlin Gradle Plugin 1.5.21 及以上版本	Xcode 11.0 及以上版本 iOS 11.0 及以上版本设备项目设置有效的开发者签名	依赖 Python Requests 库 CMake 3.25.1 及以上版本	暂无环境要求	暂不支持 H5	已配置 Flutter 鸿蒙开发环境（参考鸿蒙官方文档） Flutter 版本使用 v3.27.5-ohos-0.0.2

集成 SDK

通过 Flutter 依赖

NIM Flutter SDK 已发布到 Dart 和 Flutter 项目提供包管理服务的平台 pub.dev 库，您可以通过配置 pubspec.yaml 自动下载更新。

在项目的 pubspec.yaml 文件中添加以下依赖。
```
YAMLdependencies:
nim_core_v2: ^10.9.6
```
- 以上示例中的 10.9.6 可以更换为其他版本号，具体请参考更新日志，推荐您使用最新版本的 SDK。
- 鸿蒙版本接入方式采用 git 依赖，暂未上传至 pub。添加以下 git 依赖：
```
yamldependencies:
nim_core_v2:
    git:
    url: "https://github.com/netease-kit/NIM-Flutter-SDK-OHOS.git"
```
通过 Shell 或者 IDE 执行以下命令，下载依赖包。
```
Bashflutter pub get
```

集成到 Web 平台

从 v10.9.6 版本开始，Web 端实现进行了重大架构升级，从 TypeScript 中间层架构迁移到 Dart dart:js_interop 直接调用架构。

此变更对用户接入方式有影响，请按照版本自行变更集成方式。

v10.9.6 及以上版本

架构流程：

Dart (WebXxxService)
  ↓ dart:js_interop 直接调用
NIM Web SDK

您可以手动下载 Web SDK（NIM_BROWSER_SDK.js），并将其复制到 Flutter Web 目录下。也可以直接在 Flutter 项目的 web 目录下执行 bash web/download_nim_sdk.sh 命令运行以下脚本自动下载。

#!/bin/bash
# Copyright (c) 2022 NetEase, Inc. All rights reserved.
# Use of this source code is governed by a MIT license that can be
# found in the LICENSE file.

# ============================================================
# NIM Web SDK 预下载脚本
# 在执行 flutter build web 之前运行此脚本，将 NIM Web SDK
# 下载到 web/ 目录，避免用户运行时依赖外部 CDN 网络。
#
# 用法:
#   bash web/download_nim_sdk.sh
#   或在项目根目录执行:
#   bash example/web/download_nim_sdk.sh
# ============================================================

set -e

NIM_SDK_VERSION="10.9.80"
# V2 API 使用 dist/v2 目录下的 SDK
NIM_SDK_URL="https://unpkg.com/nim-web-sdk-ng@${NIM_SDK_VERSION}/dist/v2/NIM_BROWSER_SDK.js"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
OUTPUT_FILE="${SCRIPT_DIR}/NIM_BROWSER_SDK.js"

echo "================================================"
echo " NIM Web SDK 预下载脚本"
echo " 版本: nim-web-sdk-ng@${NIM_SDK_VERSION}"
echo " 目标: ${OUTPUT_FILE}"
echo "================================================"

# 检查 curl 是否可用
if ! command -v curl &> /dev/null; then
  echo "[ERROR] 未找到 curl，请先安装 curl 后重试。"
  exit 1
fi

echo "[INFO] 正在下载 NIM Web SDK..."
curl -fSL --progress-bar \
  -o "${OUTPUT_FILE}" \
  "${NIM_SDK_URL}"

if [ $? -eq 0 ]; then
  FILE_SIZE=$(du -sh "${OUTPUT_FILE}" | cut -f1)
  echo "[SUCCESS] 下载完成！文件大小: ${FILE_SIZE}"
  echo "[SUCCESS] 已保存至: ${OUTPUT_FILE}"
else
  echo "[ERROR] 下载失败，请检查网络连接后重试。"
  echo "[ERROR] 下载地址: ${NIM_SDK_URL}"
  exit 1
fi

echo ""
echo "现在可以执行 flutter build web 进行构建。"

配置 index.html 文件。

在 web/index.html 的 <body> 标签内，Flutter 脚本之前引入 NIM Web SDK。

<!DOCTYPE html>
<html>
<head>
  <base href="$FLUTTER_BASE_HREF" />
  <meta charset="UTF-8" />
  <title>Your App</title>
  <script src="flutter.js"></script>
</head>
<body>
  <!-- 引入 NIM Web SDK（必须在 Flutter 脚本之前） -->
  <script src="NIM_BROWSER_SDK.js"></script>
  
  <!-- 如需存储功能，引入 AWS S3 SDK（可选） -->
  <script src="https://sdk.amazonaws.com/js/aws-sdk-2.410.0.min.js"></script>
  <script>
    window.s3 = AWS.S3;
  </script>
  
  <!-- Flutter 启动脚本 -->
  <script src="flutter_bootstrap.js" async></script>
</body>
</html>

v10.9.6 以下版本

架构流程：

Dart (MethodChannelService)
  ↓ invokeMethod() → JSON 序列化
  ↓ context.callMethod('dartCallNativeJs', ...)
JS Bridge (index.umd.js / dartCallNativeJs)
  ↓ TypeScript 中间层
NIM Web SDK

您需要在 Flutter Web 项目的 index.html 文件中添加以下脚本引用：

添加文件上传 SDK，例如 AWS SDK。

HTML<script src="https://sdk.amazonaws.com/js/aws-sdk-2.410.0.min.js"></script>

添加网易云信 IM SDK，例如 10.4.0 版本。

HTML<script src="https://yx-web-nosdn.netease.im/package/1747194828266/index.umd_10_4_0.js?download=index.umd_10_4_0.js"></script>

确保 index.html 包含必要的桥接代码，用于 Dart 和 JavaScript 之间的通信。

JavaScript<script>
  window.s3 = AWS.S3
  window.onload = function () {
    // Flutter 初始化代码
    try {
      _flutter.loader
        .loadEntrypoint({
          serviceWorker: {
            // 需要您自行指定 serviceWorkerVersion，例如从 package.json 指定版本号
            serviceWorkerVersion: <yourServiceWorkerVersion>,
          },
        })
        .then(function (engineInitializer) {
          return engineInitializer.initializeEngine()
        }).then(appRunner => {
          window.$flutterWebGlobal = {
            rootService: new window.FlutterWeb.default(),
          }
          appRunner.runApp();
        })
    } catch (error) {
      console.log(error);
    }
  };

  async function dartCallNativeJs(callInfo = {}) {
    // JavaScript 桥接函数，允许 Dart 调用 JavaScript
    // 完整实现请参考完整示例
     const { serviceName, method, params, successCallback, errorCallback } =
         callInfo;
     try {
       console.log('dartCallNativeJs: ', callInfo)
       const service = window.$flutterWebGlobal.rootService[serviceName];
       if (!service) {
         throw new Error(`You do not implement this service: ${serviceName}`);
       }
       if (!service[method]) {
         throw new Error(`This method: ${method} is not implemented on this service: ${serviceName}`);
       } 
       // 参数中删除null       
       function removeNullValue(obj) {
         if (obj === null || obj === undefined) {
           return obj;
         }
         if (typeof obj === 'object') {
           Object.keys(obj).forEach(key => {
             if (obj[key] === null || obj[key] === undefined) {
               delete obj[key];
             } else {
               removeNullValue(obj[key]);
             }
           });
         }
         return obj;
       }
       removeNullValue(params);
       // 参数中删除serviceName
       if (params.hasOwnProperty('serviceName')) {
         delete params.serviceName;
       }
       const res = await service[method](params);
       successCallback(res)
     } catch (error) {
       console.error('dartCallNativeJs failed: ', error)
       errorCallback(error)
       throw error
     }
  }
</script>

注意： Web 平台集成需要确保您的项目支持 Flutter Web，并且上述脚本正确加载到项目的 index.html 文件中。

升级指南

若您已集成 Flutter Web SDK，请按照以下步骤进行升级。

移除旧的桥接文件。
- 删除 web/index.umd.js 文件。
- 删除 web/index.html 中对 index.umd.js 的 <script> 引用。
移除旧的桥接函数。
- 删除 web/index.html 中的 window.$flutterWebGlobal = {} 初始化。
- 删除 web/index.html 中的 dartCallNativeJs 函数定义。
NIM Web SDK 引入
- 确保 web/index.html 中有 NIM Web SDK 的 <script> 引入。
- SDK 版本建议使用 v10.7.6 或更高版本。
检查 Dart SDK 版本。
- Web 端现在要求 Dart SDK >=3.3.0。
- 如果您的项目 Dart SDK 版本较低，请先升级。

其他配置

运行 SDK [Windows]

该步骤仅适用 Windows 平台，其他平台可直接跳过此步骤。
Flutter v10.9.6 及以上版本可直接跳过此步骤。

Flutter v10.9.6 之前的版本，运行 Windows SDK 时需要将 SDK 复制到项目工程的 run 目录下，然后再运行 SDK。例如：

将 xxx\nim_core_v2\nim_core_v2_windows\nim_sdk\bin 中的文件复制到 xxx\nim_core_v2\nim_core_v2\example\build\windows\x64\runner\Debug 中。

防混淆配置 [Android]

该步骤仅适用 Android 平台，其他平台可直接跳过此步骤。

使用 kotlin-gradle-plugin，在工程根目录的 build.gradle 文件中添加以下配置。

JSONbuildscript {
    ext.kotlin_version = '1.9.0'
    repositories {
        google()
        mavenCentral()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:7.3.1'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

在 app/build.gradle 中，配置 packagingOptions，示例如下：

Groovy/ 新增：启用 kotlin 插件
    apply plugin: 'kotlin-android'

    android {
        // 其他配置
        ...

        packagingOptions {
            pickFirst 'lib/x86/libc++_shared.so'
            pickFirst 'lib/x86_64/libc++_shared.so'
            pickFirst 'lib/armeabi-v7a/libc++_shared.so'
            pickFirst 'lib/arm64-v8a/libc++_shared.so'
        }
    }

更多信息请参考 Android 的代码防混淆。

下一步

完成 SDK 集成后，您可以尝试初始化。

常见问题

编译错误 [Windows]

当编译项目时，出现类似以下报错信息时：

您需要在 Windows 目录下的 CMakeList.txt 文件中添加以下代码，以解决上述问题。

TXTfunction(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX- /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE "$<$<CONFIG:Debug>:_DEBUG>")
endfunction()

升级错误

Q：升级后 Web 端报错 "V2NIM is not defined"。

A：请检查 web/index.html 中是否正确引入了 NIM Web SDK 的 <script>标签。

Q：升级后编译报错 "Unsupported Dart SDK version"。

A：新版 Web 实现要求 Dart SDK>=3.3.0，请升级您的 Flutter/Dart 版本。

Q：Web 端框架升级对原生平台（Android/iOS/Windows/macOS）是否受影响？

A：不受影响。此变更仅涉及 Web 端实现，原生平台的实现方式和接入方式保持不变。

此文档是否对你有帮助？

有帮助

去反馈

环境要求
集成 SDK
通过 Flutter 依赖
集成到 Web 平台
其他配置
运行 SDK [Windows]
防混淆配置 [Android]
下一步
常见问题
编译错误 [Windows]
升级错误