# 频道连接状态管理 (/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection/flutter)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在实时音视频场景下,App 端与声网 SD-RTN™ 之间的连接状态会随着客户端加入或离开频道而发生变化,也可能由于网络或鉴权问题而导致连接中断。
本文介绍各种频道连接状态,状态改变原因和处理方式,帮助你更好地管理用户和排除网络故障。
## 技术原理 [#技术原理-7]
### 连接状态 [#连接状态-14]
当连接状态发生变化时,声网会发送 `onConnectionStateChanged` 回调。 下图展示各种连接状态,以及用户从加入到离开频道的过程中连接状态如何改变:
### 断线重连 [#断线重连-7]
通信过程中,如果因网络问题导致连接断开,SDK 会自动开启断线重连机制。下图展示本地用户 (UID1) 和远程用户 (UID2) 在以下过程中收到的回调:本地用户加入频道、发生网络异常、连接中断、重新加入频道。

图解如下:
- T0:SDK 接收到 UID 1 的 `joinChannel` 请求。
- T1:调用 `joinChannel` 200 ms 后,UID1 加入频道。同时,UID 1 收到 `onConnectionStateChanged(connectionStateConnecting, connectionChangedConnecting)` 回调。成功加入频道后,UID 1 收到 `onConnectionStateChanged(connectionStateConnected, connectionChangedJoinSuccess)` 和 `onJoinChannelSuccess` 回调。
- T2:因网间传输延迟,UID 2 感知 UID 1 加入频道约有 100 毫秒的延迟,此时 UID 2 收到 `onUserJoined` 回调。
- T3:某个时间点 UID 1 客户端因断网等原因导致上行网络变差。SDK 自动尝试重新加入频道。
- T4:如果 UID 1 连续 4 秒没有收到服务器发送的任何数据,UID 1 收到 `onConnectionStateChanged(connectionStateReconnecting, connectionChangedInterrupted)` 回调;同时 SDK 继续尝试重新加入频道。
- T5:UID 1 收到 `onConnectionStateChanged(connectionStateReconnecting, connectionChangedInterrupted)` 后连续 10 秒没有收到服务器发送的任何数据,UID 1 会收到 `onConnectionLost` 回调;同时 SDK 继续尝试重新加入频道。
- T6:如果 UID 2 连续 20 秒没有收到来自 UID 1 的任何数据,则 SDK 判断 UID 1 离线。UID 2 收到 `onUserOffline` 回调。
- T7:如果 UID 1 收到 `onConnectionStateChanged(connectionStateReconnecting, connectionChangedInterrupted)` 后连续 20 分钟无法重新加入频道,SDK 不再继续尝试。UID 1 收到 `onConnectionStateChanged(connectionStateFailed, connectionChangedJoinFailed)` 回调;用户需要退出当前频道,然后重新加入频道。
## 前提条件 [#前提条件-7]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 操作步骤 [#操作步骤-7]
本节介绍如何使用 `onConnectionStateChanged` 回调来监控频道连接状态的变化。
在你的项目中,打开管理 `RtcEngineEventHandler` 的文件,在 `RtcEngineEventHandler` 初始化过程中加入 `onConnectionStateChanged`。
你可以从日志中读取当前连接状态,以及状态更改的触发原因。
另外,`onConnectionStateChanged` 中的 `reason` 参数也解释了连接状态改变的原因,可帮助你进行网络故障排除。有关频道连接状态变化的原因以及排障方式,详见[状态说明及排障指导](#connection_reason)。
## 参考信息 [#参考信息-7]
### 连接状态 [#连接状态-15]
如前文图中所示,App 在加入和离开频道前后可能出现以下 5 种连接状态:
| 连接状态 | 描述 |
| --- | --- |
| Disconnected | [channel-connection-flutter-markdown-0-1-1 details](#table-slot-channel-connection-flutter-markdown-0-1-1) |
| Connecting | 调用 `joinChannel` 方法后的瞬时状态。 |
| Connected | 发生在 App 成功加入频道后。SDK 还会触发 `onJoinChannelSuccess` 回调,上报本地客户端已经加入频道。 此时用户可以发布或订阅频道中的音频和视频。 |
| Reconnecting | [channel-connection-flutter-markdown-0-4-1 details](#table-slot-channel-connection-flutter-markdown-0-4-1) |
| Failed | 连接失败。发生在 SDK 在 20 分钟内无法加入频道、并且 SDK 停止重新连接频道时。 此时需调用 `leaveChannel` 离开当前频道,再调用 `joinChannel` 再次加入频道。 |
**channel-connection-flutter-markdown-0-1-1 details**
初始连接状态。它通常发生在:
- 调用 `joinChannel` 之前。
- 调用 `leaveChannel` 之后。
**channel-connection-flutter-markdown-0-4-1 details**
发生在连接中断时。SDK 会在中断后自动尝试重新连接。
- 如果重新加入频道成功,SDK 会触发 `onRejoinChannelSuccess` 回调。
- 如果 10 秒内没有加入频道,SDK 会触发 `onConnectionStateChanged(connectionStateReconnecting, connectionChangedLost)`,同时继续尝试重新加入频道。
### 状态说明及排障指导 [#状态说明及排障指导-7]
`onConnectionStateChanged` 中的 `reason` 参数描述了连接状态更改原因。
下表列出了不同连接状态和状态变化原因之间的映射关系,以及发生网络中断时故障时的处理方法。
| 连接状态 | 状态说明和排障指导 |
| --- | --- |
| Disconnected | [channel-connection-flutter-markdown-1-1-1 details](#table-slot-channel-connection-flutter-markdown-1-1-1) |
| Connecting | [channel-connection-flutter-markdown-1-2-1 details](#table-slot-channel-connection-flutter-markdown-1-2-1) |
| Connected | [channel-connection-flutter-markdown-1-3-1 details](#table-slot-channel-connection-flutter-markdown-1-3-1) |
| Reconnecting | [channel-connection-flutter-markdown-1-4-1 details](#table-slot-channel-connection-flutter-markdown-1-4-1) |
| Failed | [channel-connection-flutter-markdown-1-5-1 details](#table-slot-channel-connection-flutter-markdown-1-5-1) |
**channel-connection-flutter-markdown-1-1-1 details**
- `LeaveChannel`(5):用户离开频道。
- `InvalidToken`(8):Token 无效,请使用有效的 Token 加入频道。
**channel-connection-flutter-markdown-1-2-1 details**
- `Connecting`(0):App 正在尝试加入声网频道。
**channel-connection-flutter-markdown-1-3-1 details**
- `JoinSuccess`(1):App 已成功加入频道。
**channel-connection-flutter-markdown-1-4-1 details**
- `Interrupted`(2):当网络连接中断时,SDK 自动重新连接频道,连接状态持续变化。 关于自动重连时连接状态如何改变, 详见[断线重连](#reconnection)。
- `Lost`(16):SDK 和服务器失去连接。
- `SettingProxyServer`(11):由于设置了代理服务器,SDK 尝试重连。
- `ClientIpAddressChanged`(13):客户端 IP 地址变更。如多次收到该状态码,请提示用户更换网络后尝试重新加入频道。
- `KeepAliveTimeout`(14):SDK 和服务器连接保活超时,进入自动重连状态。
- `RenewToken`(12):更新 Token 引起网络连接状态改变。
**channel-connection-flutter-markdown-1-5-1 details**
- `BannedByServer`(3):用户被服务器禁止。
- `JoinFailed`(4):SDK 在 20 分钟内持续尝试加入频道失败,停止尝试重连。 你需要调用 `leaveChannel` 离开当前频道,然后调用 `joinChannel` 重新加入频道。
- `InvalidAppId`(6):App ID 无效,请使用有效的 App ID 加入频道。
- `InvalidChannelName`(7):频道名无效,请检查频道名中是否包含非法字符,并使用有效的频道名加入频道。
- `TokenExpired`(9):Token 已过期。请从 App 服务器获取新的 Token,然后调用 `joinChannel` 重新加入频道。
- `RejectedByServer`(10):此用户被服务器禁止。一般有以下原因:
- 本地用户已加入频道后,App 再次调用加入频道的 API,如 `joinChannel`。
- App 调用了 `startEchoTest`,但没有调用 `stopEchoTest` 结束回声测试。
### API 参考 [#api-参考-8]
- [`getConnectionState`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getconnectionstate)
- [`onConnectionStateChanged`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onconnectionstatechanged)