> 本文是《BK7258 适配 LiveKit 实战》系列第 3 篇。  

> 文章基于真实工程代码，聚焦可复现的迁移路径与调试方法。  

> 建议先阅读上一篇，再继续本篇内容。

> BK7258 开发基于 xiaozhi 工程，移植 esp32 livekit 到工程下。

---

## 1. 对应架构文档哪一部分

目标：先看总流程，再钻函数细节，避免一开始陷入局部调试。

                                                                        [LiveKit 连接总流程]

---

## 2. 三层协作关系

### Room 层（`livekit.c`）

- 提供 create/connect/destroy 入口

- 负责对外 API 的生命周期管理

### Engine 层（`engine.c`）

- 维护连接状态机

- 处理 Join、协商、重连、媒体事件

### Signaling 层（`signaling.c`）

- WebSocket 建连

- protobuf 信令消息收发

迁移时建议：先保证三层职责边界稳定，再做性能优化。

---

## 3. 标准连接路径（从入口到 JOIN）

1. `livekit_room_create` 创建房间句柄  

2. `livekit_room_connect` 发起连接  

3. `engine_connect` 进入连接状态机  

4. `signal_connect` 建立 WebSocket  

5. 收发 JOIN 相关消息，进入已连接态

这条路径中的每一步都应有状态日志，否则失败时很难断点定位。

---

## 4. 连接阶段的常见失败点

- WebSocket 建连成功但未收到 JOIN 响应

- JOIN 成功但状态机未切换到可协商状态

- 协商触发时机早于引擎状态就绪

建议先做“状态完整性检查”，再查网络细节。

---

## 5. 和 BK7258 适配直接相关的点

- `signal_connect` 底层 ws/tls 适配是否完整

- 引擎状态机的并发访问是否加了门控

- 重连后旧连接资源是否确实释放

---

## 6. 本篇结论

连接流程排障的关键不是“抓一个报错”，而是确保 Room/Engine/Signaling 三层协作的状态一致性。

---

## 写在最后

ESP32 livekit 项目 GitHub 仓库：https://github.com/livekit/client-sdk-esp32

下一篇将继续展开：第 4 篇《`join_room()` 深入：URL 组装、Token、协议参数与首连排障》。