React Native聊天功能集成：Sendbird UIKit架构解析与实战指南-平芜编程栈

1. 项目概述：Sendbird UIKit for React-Native

如果你正在用 React Native 开发一款需要集成聊天功能的 App，并且希望这个功能既专业又快速上线，那么你很可能已经听说过或者正在寻找一个成熟的 UI 组件库。Sendbird UIKit for React-Native 就是这样一个解决方案。它不是一个简单的 SDK，而是一个开箱即用的、基于 Sendbird 底层 Chat SDK 构建的完整 React Native UI 套件。简单来说，它把聊天界面中那些复杂且重复的组件——比如消息列表、输入框、频道列表、用户头像、已读回执、消息状态等等——全部打包好了，并且提供了完整的交互逻辑和状态管理。你不需要从零开始画界面、处理消息的发送接收时序、管理本地缓存与网络同步，只需要像搭积木一样，引入几个核心的 Fragment（可以理解为预置的屏幕或页面），配置一下主题，一个功能完备的聊天模块就基本成型了。

我最初接触它是因为公司的一个社交项目，时间紧任务重，自研聊天模块至少需要2-3个人月，而且后续的维护成本（比如消息同步、性能优化、多端一致性）会是个无底洞。Sendbird UIKit 的核心价值就在于，它用经过大规模商业应用验证的代码，帮你规避了这些“坑”。这个仓库sendbird/sendbird-uikit-react-native正是这个 UI 套件的开源代码库。它是一个采用 Lerna 和 Yarn Workspaces 管理的 Monorepo（单体仓库），里面不仅包含了 UIKit 的主体代码，还有配套的 UI 基础组件包、React Hooks 包、工具包以及一个功能完整的示例应用。这意味着如果你对默认的 UI 样式或某些交互逻辑不满意，你有完全的自主权去修改源码，或者参考其实现来构建自定义组件，这是使用闭源 SaaS 服务所不具备的灵活性。

2. 核心架构与 Monorepo 设计解析

理解这个仓库的结构，是高效使用和定制化开发的关键。它不是一个单一的项目，而是一个精心设计的“项目家族”，每个包职责清晰，通过 Monorepo 统一管理依赖和构建流程。

2.1 仓库目录结构深度解读

打开项目根目录，你会看到几个核心的packages和一个sample目录。这不仅仅是代码的堆放，更体现了模块化设计思想。

packages/uikit-react-native：这是主角，我们通常通过npm install @sendbird/uikit-react-native安装的就是这个包。它包含了所有暴露给终端开发者的 React Native 组件和 Fragment，例如GroupChannelListFragment,GroupChannelFragment,createGroupChannelFragment等。它的内部会依赖下面几个兄弟包，组装成最终可用的 UI 套件。如果你想深度定制，比如修改消息气泡的渲染逻辑，主要就是在这个包里动手术。
packages/uikit-react-native-foundation：这是 UI 的基石。它定义了一套统一的设计语言系统，包括颜色主题 (Palette)、字体样式 (Typography)、间距常量、通用的原子组件（如Button,Text,LocalizationContext等）。所有在uikit-react-native中看到的组件，其样式都来源于此。这样做的好处是，你只需要修改 Foundation 包中的主题变量，就能全局改变整个聊天界面的视觉风格，确保了设计的一致性。例如，你想把主色调从蓝色改成绿色，只需要修改Palette中的primary-300等颜色值。
packages/uikit-chat-hooks：这是逻辑的核心。它封装了所有与聊天业务相关的 React Hooks，例如useGroupChannelList,useGroupChannelMessages,useUserProfile等。这些 Hook 内部处理了与 Sendbird 服务器的连接、消息的订阅与发布、列表的分页加载、本地状态更新等复杂的数据流和副作用。UIKit 的组件层主要消费这些 Hook 提供的数据和函数。如果你需要构建一个完全自定义的 UI 但复用其业务逻辑，直接使用这些 Hook 是最高效的方式。
packages/uikit-utils：工具函数合集。包含日期格式化、字符串处理、文件类型判断、平台检测等通用的工具函数。这些是支撑其他包运行的“螺丝刀”。
sample：这不是一个简单的“Hello World”示例，而是一个功能齐全的演示应用。它完整集成了 UIKit，并展示了关键功能的实现，如自动登录、推送通知集成、全局未读消息数统计等。这是你学习和调试的最佳入口。通过运行它，你可以直观地看到所有组件的最终效果，并且其源码 (sample/src) 清晰地展示了如何在实际项目中集成和配置 UIKit。

2.2 Monorepo 与开发工具链

项目使用Yarn Workspaces和Lerna来管理这种多包结构。Yarn Workspaces 负责在根目录统一安装node_modules，并智能地将依赖链接到各个子包中，避免重复安装，也解决了包之间的相互引用问题（通过yarn workspace @sendbird/uikit-react-native add some-package）。Lerna 则负责版本管理和发布，可以一键对所有发生变更的包进行版本号升级和发布到 npm。

这种架构对开发者非常友好。当你在uikit-chat-hooks中修改了一个 Hook 的逻辑，在sample应用中能立刻看到效果，因为它们在同一个仓库内是直接引用的源码，而不是编译后的 npm 包。这极大地提升了本地开发的联调效率。

注意：环境准备的坑点官方要求 Node.js 18+、Yarn v1（经典版）、Watchman、JDK 17+、Xcode 和 Android Studio。这里最容易出问题的是Yarn和JDK。
Yarn v1：现在很多新项目默认用 Yarn Berry (v2+)，但这个项目必须用经典版。官方推荐用 Node.js 自带的corepack来管理：先运行corepack enable，然后在项目根目录运行corepack prepare yarn@1.22.19 --activate，这样可以确保团队每个人都使用完全相同的 Yarn 版本。
JDK 17+：Android 开发环境对 JDK 版本敏感。如果你之前开发过 React Native 项目，可能系统里装的是 JDK 8 或 11。务必检查java -version，并确保JAVA_HOME环境变量指向的是 JDK 17 或更高版本的路径。在 macOS 上，使用brew install openjdk@17安装后，需要通过sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk创建软链接，并在~/.zshrc中设置export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk.jdk/Contents/Home。

3. 从零开始：运行示例应用与核心功能体验

理论说再多，不如亲手跑起来看看。运行示例应用是你理解整个项目最快的方式，这个过程本身也会帮你扫清后续集成到自己项目中的大部分环境障碍。

3.1 示例应用的安装与启动

首先，克隆仓库并安装依赖。这一步因为 Workspaces 的存在，只需要在根目录执行一次。

git clone https://github.com/sendbird/sendbird-uikit-react-native.git cd sendbird-uikit-react-native yarn install

依赖安装完成后，需要链接 iOS 的原生模块。这是 React Native 混合开发的标准步骤。

yarn sample:pod-install

这个命令本质上是在sample/ios目录下执行了pod install，安装 UIKit 所依赖的 CocoaPods 库。

接下来就可以启动应用了。我强烈建议在两个独立的终端标签页中分别启动 Metro 打包器和运行应用，这样日志更清晰，出问题时也更好排查。

终端1：启动 Metro Bundler

cd sample yarn start # 或者 npx react-native start

保持这个终端运行，它会负责 JavaScript 代码的实时打包和提供调试服务。

终端2：运行 Android 应用

cd sample npx react-native run-android

终端2：运行 iOS 应用 (在 macOS 上)

cd sample npx react-native run-ios

如果一切顺利，你会在模拟器或真机上看到一个聊天应用。首次运行会要求你输入 User ID 登录。这里使用的是 Sendbird 提供的一个演示用的APP_ID，你可以直接登录进入，体验频道列表、创建频道、发送文本/图片消息等核心功能。

3.2 连接你自己的 Sendbird 应用

用演示的APP_ID只能和同样使用该 ID 的随机用户聊天。要体验完整功能或进行真实开发，你需要使用自己的APP_ID。

访问 Sendbird Dashboard ，注册并创建一个新的 “Application”。创建成功后，在 “Application” 页面就能看到你的APP_ID（一串由数字和字母组成的 UUID）。
在示例项目sample目录下，创建文件src/env.ts。

在该文件中写入你的APP_ID：

// sample/src/env.ts export const APP_ID = 'YOUR_APPLICATION_ID_HERE'; // 替换成你的真实 ID

重新运行应用 (yarn start+npx react-native run-android/ios)。现在登录后，你创建的用户和发送的消息都会在你的 Sendbird 应用后台看到，并且你可以通过 Dashboard 管理用户、频道和消息。

实操心得：环境变量与类型安全示例中使用env.ts文件是一种简单的配置方式。在实际生产项目中，我推荐使用react-native-config这样的库来管理环境变量，可以为不同构建变体（Debug/Release，甚至不同环境如 Staging/Production）设置不同的APP_ID。同时，确保这个文件被添加到.gitignore中，避免敏感信息泄露。

3.3 示例应用中的关键功能剖析

示例应用 (sample/App.tsx) 虽然代码不多，但展示了 UIKit 最精髓的集成模式：

初始化与用户管理：它使用@sendbird/uikit-react-native导出的SendbirdUIKitContainer组件来包裹整个应用。这个容器组件在内部处理了 Sendbird SDK 的初始化和用户认证。
Fragment 的直接使用：登录后，应用直接渲染了GroupChannelListFragment。这个 Fragment 自带了一个完整的频道列表页面，包括搜索栏、创建频道按钮、列表项（显示最后一条消息、未读计数、时间戳等）。你不需要为这个页面写任何布局或业务逻辑代码。
导航集成：示例中使用 React Navigation 进行页面跳转。当点击一个频道时，会导航到GroupChannelFragment，并传入channelUrl作为参数。这个 Fragment 则渲染出完整的聊天对话界面。

这种“Fragment”模式是 UIKit 设计的核心。它提供的是一个个功能完整的“屏幕块”，你通过 React Navigation、React Native Router Flux 等任何你喜欢的导航库，像管理普通屏幕一样来管理这些聊天页面即可，极大地降低了集成复杂度。

4. 集成到自有项目：实战步骤与配置详解

看完了示例，是时候把它搬到我们自己的项目里了。假设你有一个全新的 React Native 项目（使用npx react-native init MyChatApp创建），以下是详细的集成步骤。

4.1 安装与基础配置

首先，在项目根目录安装 UIKit 核心包和其必要的对等依赖（peer dependencies）。

npm install @sendbird/uikit-react-native # 或者 yarn add @sendbird/uikit-react-native

这个包本身依赖@sendbird/chat(Sendbird JavaScript SDK) 和react-native相关库。安装时，npm/yarn 会自动处理。接下来，安装一些 UIKit 内部使用的原生模块依赖：

# 安装图片选择与裁剪库 npm install react-native-image-crop-picker # 安装文件访问库 (用于发送文件消息) npm install react-native-document-picker # 安装权限处理库 npm install react-native-permissions # 安装本地存储库 (用于持久化用户偏好等) npm install @react-native-async-storage/async-storage # 安装手势处理库 npm install react-native-gesture-handler # 安装安全区域处理库 npm install react-native-safe-area-context

对于 iOS，需要进入ios目录安装 CocoaPods 依赖：

cd ios && pod install

对于 Android，需要确保android/app/build.gradle中的minSdkVersion至少为 21，因为部分依赖库要求此版本。

4.2 应用入口与 UIKit 容器初始化

这是最关键的一步。我们需要用SendbirdUIKitContainer包裹你的应用根组件。这个容器负责：

初始化 Sendbird SDK 实例。
管理当前登录用户的状态。
提供全局的 UI 主题和本地化上下文。

在你的入口文件（例如App.tsx）中：

import React from 'react'; import { SendbirdUIKitContainer } from '@sendbird/uikit-react-native'; import { NavigationContainer } from '@react-navigation/native'; // 假设使用 React Navigation import AppNavigator from './src/navigation/AppNavigator'; // 你的导航器 const App = () => { // 你的 Sendbird 应用 ID const APP_ID = 'YOUR_APPLICATION_ID_HERE'; return ( <SendbirdUIKitContainer appId={APP_ID} // 平台服务配置，用于推送通知（后续详解） platformServices={{ file: {}, // 使用默认文件服务 notification: {}, // 推送服务，需额外配置 clipboard: {}, // 剪贴板服务 }} // 本地化配置，支持多语言 localization={{ default: 'en', resource: { en: require('./src/localization/en'), ko: require('./src/localization/ko'), }, }} // 主题配置，可覆盖默认样式 theme={{ palette: { primary: '#742DDD', // 自定义主色调 onBackgroundLight01: '#FFFFFF', // ... 其他颜色 }, typography: { 'heading-1': { fontSize: 24, fontWeight: 'bold' }, // ... 其他字体样式 }, }} // 用户信息提供器，用于显示用户昵称和头像 userProfile={{ onCreateChannel: (channel, users) => { // 当创建频道时，可以自定义频道名称 return `Group with ${users.map(u => u.nickname).join(', ')}`; }, }} > <NavigationContainer> <AppNavigator /> </NavigationContainer> </SendbirdUIKitContainer> ); }; export default App;

4.3 实现登录与聊天页面导航

现在，我们需要创建登录页面和集成聊天 Fragment。假设你的导航结构有一个登录页 (LoginScreen) 和一个主页面 (HomeScreen)，主页面里包含聊天入口。

1. 登录页面 (LoginScreen.tsx)这个页面负责收集用户 ID 和昵称，并调用 UIKit 的登录方法。

import React, { useState } from 'react'; import { View, TextInput, Button, Alert } from 'react-native'; import { useSendbirdChat } from '@sendbird/uikit-react-native'; const LoginScreen = ({ navigation }) => { const [userId, setUserId] = useState(''); const [nickname, setNickname] = useState(''); const { sdk, connect } = useSendbirdChat(); // 使用 UIKit 提供的 Hook const handleLogin = async () => { if (!userId.trim() || !nickname.trim()) { Alert.alert('Error', 'Please enter both User ID and Nickname'); return; } try { // 连接 Sendbird 服务器 await connect(userId, { nickname }); // 连接成功，导航到主页面 navigation.replace('Home'); } catch (error) { Alert.alert('Connection Failed', error.message); } }; return ( <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}> <TextInput placeholder="Enter User ID" value={userId} onChangeText={setUserId} autoCapitalize="none" /> <TextInput placeholder="Enter Nickname" value={nickname} onChangeText={setNickname} /> <Button title="Log In" onPress={handleLogin} /> </View> ); };

2. 主页面与聊天 Fragment 集成 (HomeScreen.tsx)主页面可以是一个 Tab 导航页，其中一个 Tab 是聊天频道列表。

import React from 'react'; import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs'; import { GroupChannelListFragment } from '@sendbird/uikit-react-native'; import { useNavigation } from '@react-navigation/native'; const Tab = createMaterialTopTabNavigator(); const ChatListScreen = () => { const navigation = useNavigation(); return ( <GroupChannelListFragment // Fragment 渲染为整个屏幕 onPressChannel={(channel) => { // 点击频道，导航到聊天详情页，并传递频道 URL navigation.navigate('ChatDetail', { channelUrl: channel.url }); }} onPressCreateChannel={() => { // 点击创建频道按钮，导航到创建频道页 navigation.navigate('CreateChannel'); }} /> ); }; const HomeScreen = () => { return ( <Tab.Navigator> <Tab.Screen name="Chats" component={ChatListScreen} /> {/* 其他 Tab 屏幕 */} </Tab.Navigator> ); };

3. 聊天详情页 (ChatDetailScreen.tsx)这个屏幕展示具体的聊天内容。

import React from 'react'; import { GroupChannelFragment } from '@sendbird/uikit-react-native'; import { useRoute } from '@react-navigation/native'; const ChatDetailScreen = () => { const route = useRoute(); const { channelUrl } = route.params; // 从导航参数获取频道 URL return ( <GroupChannelFragment channelUrl={channelUrl} // 必须参数，指定要加载哪个频道 onPressHeaderLeft={() => { // 点击头部返回按钮，通常执行 navigation.goBack() }} onPressHeaderRight={() => { // 点击头部右侧按钮（通常是频道信息） }} // 可以覆盖消息输入框上方的自定义组件区域 renderInput={() => { // 返回自定义的输入组件，例如集成 AI 助手按钮 return null; // 默认返回 null 使用原生输入框 }} /> ); };

通过以上三步，一个具备完整聊天功能的模块就集成完毕了。GroupChannelListFragment和GroupChannelFragment承担了所有繁重的工作。

注意事项：Fragment 的生命周期与性能Fragment 内部已经优化了消息的订阅、内存管理和组件卸载时的资源清理。但需要注意：
当ChatDetailScreen被导航离开时（例如返回上一页），Fragment 组件会卸载，并自动退订该频道的实时消息。再次进入时会重新订阅。
频道列表 (GroupChannelListFragment) 默认会缓存列表数据，滚动性能较好。但如果频道数量巨大（成千上万），需要考虑结合 Sendbird SDK 的查询过滤器进行分页或搜索，UIKit 的 Fragment 已经内置了这些功能。
避免在 Fragment 外部嵌套不必要的重渲染组件。例如，不要用React.memo或复杂的状态管理去包裹整个 Fragment，这可能会干扰其内部的状态更新。

5. 高级定制与深度开发指南

UIKit 开箱即用的设计满足了80%的需求，但剩下的20%才是体现产品差异化的地方。幸运的是，这个开源库提供了从样式到逻辑的多层次定制入口。

5.1 主题与样式定制

定制样式主要有两种方式：全局主题覆盖和组件级样式覆盖。

全局主题覆盖：如前所述，在SendbirdUIKitContainer的theme属性中修改。这是最推荐的方式，能保证整个应用聊天部分样式统一。你可以修改palette（调色板）、typography（字体）、components（组件基础样式）等。具体有哪些可配置项，最好的方法是查阅uikit-react-native-foundation包中的类型定义文件，或者直接运行 Storybook 查看。

组件级样式覆盖：每个 Fragment 和基础组件都接受styles属性。例如，你想修改GroupChannelFragment中消息列表的样式：

<GroupChannelFragment channelUrl={channelUrl} styles={{ // 覆盖容器样式 container: { backgroundColor: '#f5f5f5' }, // 覆盖消息列表样式 list: { paddingHorizontal: 8 }, // 覆盖输入区域样式 input: { borderTopWidth: 1, borderTopColor: '#eee' }, }} />

更细粒度的定制，比如修改单条消息气泡的样式，需要使用Fragment的renderMessage属性，这属于高度自定义的范畴。

5.2 自定义消息类型渲染

默认支持文本、图片、文件等消息。如果你需要发送和渲染一种自定义消息（比如地理位置、商品卡片、投票），需要以下步骤：

定义自定义消息数据：使用 Sendbird SDK 的UserMessageParams或FileMessageParams的data和customType字段来存储你的结构化数据。
自定义消息渲染器：在GroupChannelFragment中，使用renderMessage属性来根据customType返回不同的 UI 组件。

import { GroupChannelFragment, useSendbirdChat } from '@sendbird/uikit-react-native'; import { MyCustomMessageBubble } from './MyCustomMessageBubble'; const ChatDetailScreen = () => { const { sdk } = useSendbirdChat(); const currentUser = sdk.currentUser; const renderCustomMessage = (props) => { const { message, onPress, onLongPress, ...rest } = props; if (message.customType === 'product_card') { const productData = JSON.parse(message.data); return ( <MyCustomMessageBubble product={productData} isSentByMe={message.sender.userId === currentUser?.userId} onPress={onPress} /> ); } // 对于其他类型，返回默认渲染器 return <GroupChannelFragment.Message {...props} />; }; return ( <GroupChannelFragment channelUrl={channelUrl} renderMessage={renderCustomMessage} /> ); };

自定义消息输入组件：你可能还需要在输入框旁添加一个按钮来触发发送自定义消息。这可以通过GroupChannelFragment的renderInput属性来实现，返回一个完全自定义的输入栏，或者使用默认输入栏但添加额外的 Action 按钮。

5.3 推送通知集成

聊天应用离不开推送。UIKit 提供了platformServices.notification接口来统一处理。以 Firebase Cloud Messaging (FCM) 为例：

安装并配置 Firebase：在项目中安装@react-native-firebase/app和@react-native-firebase/messaging，并完成 Firebase 控制台和google-services.json/GoogleService-Info.plist的配置。
创建通知服务类：实现一个符合NotificationService接口的类。

// src/services/SendbirdNotificationService.ts import messaging from '@react-native-firebase/messaging'; import notifee from '@notifee/react-native'; // 推荐使用 notifee 显示本地通知 import { NotificationService, SendbirdChat } from '@sendbird/uikit-react-native'; export class MyNotificationService implements NotificationService { private sb: SendbirdChat; constructor(sendbirdChat: SendbirdChat) { this.sb = sendbirdChat; } async getPushToken(): Promise<string> { const token = await messaging().getToken(); return token; } async onPushTokenRegistered(pushToken: string): Promise<void> { // 将 pushToken 注册到 Sendbird await this.sdk.registerPushToken(pushToken); } async onPushNotificationReceived(notification: unknown): Promise<void> { // 当应用在前台或后台收到推送时，处理通知数据 const channel = await this.sdk.groupChannel.getChannel(notification.channel_url); // 可以使用 notifee 显示本地通知 await notifee.displayNotification({ title: notification.message, body: `New message in ${channel.name}`, data: { channelUrl: channel.url }, }); } }

注入服务：在SendbirdUIKitContainer中注入这个服务。

<SendbirdUIKitContainer appId={APP_ID} platformServices={{ file: {}, notification: new MyNotificationService(), clipboard: {}, }} // ... >

5.4 模块化开发与 Monorepo 脚本使用

如果你需要修改 UIKit 本身的源码（比如修复一个 Bug 或增加一个特性），这个开源 Monorepo 的结构就派上用场了。

创建新的关键功能模块：UIKit 提供了一个便捷的脚手架脚本。如果你想贡献一个类似GroupChannelSettings的新功能模块，可以在项目根目录运行：

yarn workspace @sendbird/uikit-react-native run create-domain

然后根据提示输入功能名称（如groupChannelSettings），脚本会自动在packages/uikit-react-native/src/domain下生成对应的模块骨架，包括 Context、Provider、Hook 和 UI 组件文件。这保证了新模块的结构与现有代码一致。

管理依赖：由于是 Workspaces，为特定包添加依赖需要用yarn workspace命令。

# 为 uikit-react-native 包添加一个开发依赖 yarn workspace @sendbird/uikit-react-native add -D some-testing-library # 为根项目添加一个所有包都可能用到的依赖（如 lodash） yarn -W add lodash

版本发布：项目使用 Lerna 管理版本。当你修改了多个包并准备发布时，可以使用以下命令自动提升版本号、生成 CHANGELOG 并打 Git Tag。

# 提升一个 patch 版本 (如 1.2.3 -> 1.2.4) yarn bump:patch # 或者直接使用 lerna lerna version patch --conventional-commits --yes

6. 常见问题排查与性能优化实录

在实际开发和上线过程中，我踩过不少坑。这里把一些典型问题和解决方案记录下来，希望能帮你节省时间。

6.1 构建与运行问题

问题现象	可能原因	解决方案
iOS 编译失败：`Undefined symbol: ...`	原生依赖（CocoaPods）未正确链接或版本冲突。	1. 在`ios`目录下执行`pod deintegrate && pod install`彻底重装。 2. 检查`Podfile`中`use_frameworks!`的设置，UIKit 可能需要它。 3. 确保所有原生模块都支持当前 React Native 版本。
Android 运行崩溃：`Tried to register two views with the same name RNSBxxx`	同一个原生模块被重复安装或链接。在 Monorepo 开发中，如果某个包含原生代码的包被同时安装在根目录和 workspace 内，就可能发生。	1. 检查`android/app/build.gradle`中的`dependencies`，移除重复的`implementation`条目。 2. 遵循官方建议：将带有原生视图的依赖尽量安装在根目录(`yarn -W add package-name`)，而不是 workspace 内。
Metro 报错：`Unable to resolve module ...`	路径解析错误，常见于 Monorepo 中符号链接（symlink）问题。	1. 在项目根目录和`sample`目录分别运行`yarn install`确保依赖完整。 2. 重启 Metro bundler 并清除缓存：`yarn start --reset-cache`。 3. 检查`.yarnrc`配置，确保没有异常的设置干扰 Workspace。
`yarn sample:android`命令不工作	该命令是定义在根目录`package.json`中的组合脚本，可能在你的环境里执行顺序有问题。	最稳妥的方式：按照前面所述，在`sample`目录下，分两个终端分别运行`yarn start`和`npx react-native run-android`。

6.2 运行时与功能问题

问题现象	可能原因	解决方案
消息发送失败，提示权限错误	用户可能被禁言，或该频道设置了只有管理员/操作员可以发言。	1. 在 Sendbird Dashboard 检查该用户的角色和状态。 2. 检查频道的`isFrozen`（冻结）和`isEphemeral`（临时）属性。 3. 通过 SDK 检查当前用户在该频道的角色：`channel.myRole`。
图片/文件消息无法发送	未正确安装或配置`react-native-image-crop-picker`和`react-native-document-picker`的原生依赖，或未申请运行时权限。	1. 确保完成了这些库的 iOS`pod install`和 Android`link`（新版本 RN 一般自动链接）。 2. 在 Android`AndroidManifest.xml`和 iOS`Info.plist`中添加相应的文件/照片访问权限描述。 3. 在代码中，使用`react-native-permissions`在发送前动态申请权限。
频道列表不更新或消息不同步	网络连接不稳定，或 SDK 连接状态异常。UIKit 内部有重连机制，但极端情况可能需要手动处理。	1. 监听 SDK 的连接状态变化：`sdk.addConnectionHandler('unique_id', { onReconnectStarted, onReconnectSucceeded, onReconnectFailed })`。 2. 在`onReconnectFailed`时，可以提示用户并尝试手动调用`sdk.connect()`。 3. 确保应用前后台切换时，正确处理连接生命周期（UIKit Container 已处理大部分情况）。
自定义消息点击事件无效	在`renderMessage`中返回自定义组件时，没有正确传递或处理`onPress`和`onLongPress`属性。	确保你的自定义气泡组件接收并绑定了这些属性到根触摸组件上。例如：`<TouchableOpacity onPress={onPress} onLongPress={onLongPress}> ... </TouchableOpacity>`。UIKit 依赖这些事件来触发消息的默认操作（如复制、回复、删除）。

6.3 性能优化要点

虚拟化列表：GroupChannelFragment内的消息列表和GroupChannelListFragment的频道列表都基于 React Native 的FlatList或FlashList（如果项目使用了它）实现，自带虚拟化渲染。但要确保传递给renderMessage的自定义组件是经过React.memo优化的，避免不必要的重渲染。
图片消息优化：大量图片消息会占用大量内存。建议：
- 在发送端，使用react-native-image-crop-picker时设置合适的压缩质量 (compressImageQuality)。
- 在接收端，使用像react-native-fast-image这样的高性能图片库来替代默认的Image组件进行渲染。UIKit 允许你通过自定义FileMessage组件或覆盖Image渲染器来实现。
消息分页与本地缓存：UIKit 在打开频道时默认会加载最近的消息，并支持上拉加载更早的历史消息。要合理设置GroupChannelFragment的queryParams属性，例如messageListParams={{ prevResultSize: 50, nextResultSize: 0 }}来控制一次加载的数量。Sendbird SDK 本身有消息缓存，但 UIKit 没有提供开箱即用的离线存储。对于强离线需求，你需要自己实现一个基于AsyncStorage或SQLite的消息缓存层，这属于高级定制范畴。
避免不必要的重渲染：确保包裹SendbirdUIKitContainer的组件（通常是你的App组件）不会因为其父组件的状态更新而频繁重渲染。可以使用React.memo或状态管理工具（如 Redux, Zustand）来隔离状态。