Swift 开发圈子里隔三差五就会冒出几个名字好听的开源项目“colibri”就是其中之一。如果你搜索这个词会发现它同时指向好几个不同的仓库——有 WebSocket 库、有 UI 组件库甚至还有拼写检查器。但在我的语境里它是我折腾了大半年的一个开源即时通讯客户端名字取自蜂鸟西班牙语 colibrí寓意就是“小而快、轻而灵活”。我最初只是想做一个能跑在 macOS 上、不臃肿的聊天工具结果越做越深从 XMPP 协议细节一路踩到 SwiftUI 的底层渲染最后把整个项目的架构、模块、编译链路、调试方法都摸了个遍。这篇文章不是官方文档翻译而是把我从零开始理解、构建、调试这个“colibri”的完整过程记录下来。适合以下几类人阅读一是想了解即时通讯客户端核心模块怎么拆分的人二是准备用 Swift 做跨端 App、但对网络层和本地存储方案没底的人三是纯粹喜欢看开源项目拆解、想知道别人怎么把“轻量”落到代码层面的朋友。我会把技术选型、模块设计、关键代码、踩坑实录都摊开讲尽量做到你照着思路能自己搭出一个最小可用版本。1. 项目背景Colibri 到底做了什么1.1 名字的来历与最初的动机“colibri”这个名字确实有来头。蜂鸟每秒能扇动几十次翅膀却能在空中悬停得稳稳当当。我当时想要的正是一个“响应极快、资源占用极低”的聊天客户端所以毫不犹豫地用了这个词。它在西语里的发音是“科利布里”在法语里也一样读起来轻快很适合一个主打轻量的项目。最初动机很直白我日常工作需要同时登录多个 IM 账号但官方客户端要么内存占用几百 MB要么强行推一堆用不上的功能。我想要的客户端只需要做好三件事——收发文本消息、管理联系人、能后台挂着不占资源。抱着这个念头我把 GitHub 上几个成熟的即时通讯协议库翻了个遍最后确定用 XMPP 作为通信协议。理由很简单XMPP 是开放的、去中心化的标准协议服务器端有成熟的开源实现比如 ejabberd 或者 Prosody不需要自研服务端就能完成端到端的联调。1.2 这个项目解决的核心问题如果用一个词概括 colibri 解决的痛点那就是“轻量下的可靠性”。很多轻量客户端做小了但做不稳消息一多界面就卡网络切换后连接状态经常性“假死”。colibri 从设计上就围绕三个约束展开内存占用控制目标是在常规聊天场景下保持在 80MB 以内比不少主流客户端低一个数量级弱网适配自动重连、消息确认、本地消息队列网络抖动时不能让用户感到“消息丢了”模块可替换协议层、存储层、UI 层完全解耦底层可以从 XMPP 换成其他协议UI 可以从 SwiftUI 换成 AppKit不影响其他模块。这其实是很朴素的目标但实现过程中我发现越是朴素的需求越逼迫你把很多基础问题想清楚。比如消息的时序问题、联系人的状态同步、离线消息的拉取策略这些听起来都不难实际做起来每个都有一堆边界情况。1.3 项目的整体面貌与功能范围做出来的 colibri 是一个 macOS 原生应用后续扩展了 iOS 端主要功能包括多账号登录、联系人列表、单聊和群聊、消息历史本地存储、未读角标提醒、系统通知以及一个极简的“专注模式”只显示指定联系人的消息。界面走的是 SwiftUI 的清爽风格没有传统 IM 的侧边栏堆叠而是用三栏结构账号列表、会话列表、聊天窗口。代码层面项目分成五个主要 package一是ColibriCore包含所有的数据模型和业务逻辑二是ColibriNet负责 XMPP 连接的建立、认证、收发消息三是ColibriStore负责 SQLite 的本地存储层四是ColibriKit放一些 UI 组件和复用视图五是 App 壳工程。这样的分层在后期调试时非常有用。我经常需要单独跑命令行工具去测试网络层如果耦合在一起做不了这种隔离测试。2. 整体设计与技术选型为什么这样做2.1 协议选型为什么是 XMPP 而不是其他方案如果做一个新的 IM摆在面前的选择很多XMPP、MQTT、Matrix、甚至自己定义 WebSocket JSON 协议。我最终选 XMPP原因有三标准化程度高XMPP 的 RFC 文档非常完善而且有大量 XEP扩展协议覆盖了离线消息、消息回执、群聊、文件传输等常见需求不需要自己造轮子服务端生态成熟本地开发可以直接跑一个 Docker 版 ejabberd几分钟就能起一个带注册、群组、离线存储的服务器客户端库可直接参考虽然 Swift 没有特别完美的 XMPP 库但可以用 libstropheC 库作为底层自己包一层 Swift 封装或者直接读它的源码理解协议细节。当然XMPP 的缺点也很明显XML 格式开销大、协议细节多、调试相对繁琐。但考虑到我的核心目标是“轻量可靠”而非“极致性能”这个代价可以接受。实际上把 XML 解析换成流式的XMLStreamParser后开销完全可控。这里想强调一个观点选型不是选“最好”的而是选“最匹配你约束条件”的。如果你的项目只是做个玩具可以用最简单的 JSON over WebSocket如果你要做的是一种生产级别的 IMXMPP 反而能少走很多弯路因为很多边界场景比如同一账号多端登录、离线消息补偿它已经替你定义好了处理方式。2.2 客户端架构模块拆分的几个关键决策colibri 的架构可以用一句话概括UI 只管展示业务逻辑全部下沉到 Core 层网络和存储被抽象成协议接口。具体拆成了四层L1 应用层SwiftUI 视图、路由、动画、窗口管理L2 业务层会话管理、联系人状态聚合、消息发送前置判断、未读数计算L3 服务层网络连接管理、本地持久化、日志、通知分发L4 基础层第三方库SQLite 的 Swift 封装、XML 解析器、CryptoKit。这个分层里最关键的两个决策一个是“把网络连接封装成状态机”另一个是“消息发送必须走本地队列”。网络连接状态机是我反复重构过好几次的地方。最开始我直接用一个URLSessionWebSocketTask来管理连接后来发现断线重连逻辑没法写清楚因为“连接中”“已连接”“重连中”“手动断开”这几种状态互相转换时容易产生重复重连或者丢事件。重构后用枚举状态机表达事件驱动迁移才彻底解决这个问题。消息发送队列则是客户端稳定性的基石。每一条用户想要发送的消息会先写入 SQLite 的outbox表标记为pending然后再由后台任务真正执行发送发送成功改成sent失败会做指数退避重试。这个机制保证了即使 App 在发送中途崩溃重启后也能恢复未发送的消息不会出现“用户明明点了发送对方却没收到”的问题——这是聊天软件里最破坏信任感的一种 Bug。2.3 与同类轻量客户端的差异化和同样打着“轻量”旗号的客户端比colibri 的差异点在于“不过度裁剪”。很多轻量客户端砍掉了消息历史、砍掉了多账号、砍掉了群聊能力只留下一个极简聊天框但我觉得真正的轻量不是功能少而是每个功能都做到恰好够用、不拖泥带水。所以在 colibri 里你找不到“换肤”“表情市场”“短视频”这类东西但 XMPP 协议层的能力比如离线消息、群聊、多端同步全部都保留了。另外一个差异化是在“本地优先”local-first上的实践。所有消息的读写都以本地数据库为准网络只是同步通道。这意味着即使完全断网用户也能翻到一年前的聊天记录而不会因为服务器端清理数据而丢失。这一点我在项目文档里反复强调过它也是很多 IM 用户最深的需求之一。3. 核心模块实现要点一步步拆给你看3.1 网络层从 TCP 到 TLS 再到 XMPP 流网络层是最先写的模块也是最容易出错的地方。XMPP 的通信流程看起来简单——建立 TCP 连接、做 TLS 握手、走 XML 流——但实际每一步都有坑。第一步是建立 TCP 连接和 TLS 握手。在 Swift 里可以用Network.framework的NWConnection也可以用底层的BSD Socket。我用的是NWConnection因为它天然支持 TLS、支持 IPv4/IPv6 切换而且设置NWProtocolTLS.Options里的sec_protocol_options_set_min_tls_protocol_version很方便。连接成功后就要发送 XMPP 的流头?xml version1.0? stream:stream toexample.com xmlnsjabber:client xmlns:streamhttp://etherx.jabber.org/streams version1.0这里踩过一个坑XML 声明必须是version1.0且不能有额外的空白字符否则某些服务器会直接关闭流。我开始时在拼接字符串时多了一个换行导致连接总是被重置花了半天才定位到问题。握手之后的认证我推荐用 SASL SCRAM-SHA-1。它的实现逻辑是客户端发送auth mechanismSCRAM-SHA-1服务器返回挑战客户端计算客户端签名再回传最后验证服务器签名。这段逻辑如果不想自己写可以用现成的 crypto 库但要特别注意 Base64 编码的细节——CryptoKit 的Data.base64EncodedString()默认是标准编码而 XMPP 里要求的是不带换行的 Base64两者在默认配置下是一致的但注意别在传输前调用data.base64EncodedData()再转一遍很容易多出一层编码导致认证失败。一个值得参考的连接状态管理代码骨架大概是这个样子的enum ConnectionState { case disconnected case connecting case authenticating case connected case reconnecting(attempt: Int) case manuallyDisconnected } enum ConnectionEvent { case userInitiatedConnect case socketConnected case tlsHandshakeCompleted case authenticated case streamClosed case error(Error) case userInitiatedDisconnect }用事件驱动状态迁移每个状态都只处理它关心的事件代码就非常清晰。我建议所有做 IM 类项目的朋友都采用这种思路而不是把重连逻辑分散在多个回调里。3.2 数据层SQLite 存储与消息时序消息存储是整个应用中我最满意的一部分。选型时考虑过 Core Data、Realm、SQLite最后选了 SQLite直接原因是我需要精确控制查询语句以及想要一个纯 C 的存储引擎来减小二进制体积。Swift 侧用了 GRDB.swift 这个封装它对 SQLite 的 C API 包得比较薄使用体验接近自己写 SQL。核心表结构有三张conversations会话表单聊和群聊都放在这里字段包含id、typesingle/group、remote_jid、last_message_time、unread_countmessages消息表字段有id、conversation_id、from、to、body、timestamp、statussending/sent/delivered/read/failedoutbox待发送消息表和messages的区别是它只存“尚未确认送达”的消息有独立的retry_count字段。消息存储中最大的坑在“时序一致性”。XMPP 并没有规定服务器必须以时间顺序分发消息所以多客户端同时在线时消息到达顺序可能与时间戳不一致。我的方案是本地展示顺序一律以本地收到消息时的时间为准不依赖服务器时间戳做排序服务器时间戳只用于展示“消息发送时间”。这样做有一个很棒的效果——慢网络下先发出去的消息虽然在 UI 上排到了后面但用户感知是“消息按到达顺序显示”反而更自然。3.3 联系人管理在线状态与头像同步联系人管理这块我一开始天真地以为无非是拿roster再监听 presence但实际做了才发现“在线状态”这东西相当微妙。XMPP 的 presence 是推送式、无持久化的你用一台设备上线vCard 或者 avatar 这类信息也不是全量推送必须主动请求。我的做法是三层缓存Roster 层启动时先拉取联系人列表本地数据库对比后增量更新Presence 层监听全局 presence 广播用PriorityQueue记录每个联系人的在线状态和优先级如果有多个资源手机、桌面在线取优先级最高的状态展示vCard/Avatar 层启动时批量请求联系人头像的 SHA1 哈希和本地缓存比对不一致才重新拉取图片。三层缓存做下来联系人列表的流畅度提升非常明显。比较关键的一点是“不要在收到每条 presence 时都刷新 UI”——应该做 debounce统一攒 500ms 再更新一次列表否则大量联系人同时上线时界面会有明显的抖动。头像的存储我用的是文件缓存而不是数据库。具体做法是Caches/avatars/{sha1}.jpg数据库只存一条记录映射jid - sha1 - 文件名。这样每次检查头像是否更新只要比对哈希值文件不存在再下载逻辑非常简单而且天然避免了重复下载。3.4 通知模块本地通知与远程推送的取舍移动端即时通讯不可避免要处理通知。colibri 最终选择的是“本地通知为主远程推送可选”。为什么会这样选择原因是 XMPP 的推送扩展 XEP-0357 需要服务器端配合而我不想把项目搞得太依赖特定服务器。本地通知的思路是App 在后台时保持长连接收到消息后立即生成一个本地通知。这个方案在 iOS 上并不能“长期挂后台”但 macOS 上没问题如果做成 iOS 版则需要配合 VoIP 或者后台模式来延长连接时间。远程推送我留了一个接口用PushKit 自建网关把 XMPP 消息转换成 APNs 推送但这块代码在仓库里用的是 stub 实现原因是我还没找到足够多的精力去维护一个稳定网关。很多开源客户端都有类似的取舍——不是做不到而是维护成本太高。我认为这种“先做核心、再留扩展点”的做法很适合个人项目。先把本地通知做到极致让桌面端体验接近原生 IM移动端的推送问题等真正有用户需求了再补而不是一上来就被推送证书和各种签名配置耗掉大量时间。4. 实操过程编译、运行与联调4.1 环境准备与依赖配置如果你想把 colibri 跑起来需要准备的环境其实并不复杂macOS 13Xcode 15一个 XMPP 服务器推荐直接用 Dockerdocker run -d --name ejabberd -p 5222:5222 -p 5280:5280 ejabberd/ecs启动之后用浏览器打开http://localhost:5280/admin默认管理员账号是adminlocalhost密码在容器日志里在 ejabberd 里注册两个测试账号比如alicelocalhost和boblocalhost用于客户端联调。依赖管理用的是 Swift Package Manager。项目根目录有一个Package.swift核心依赖就三个.package(url: https://github.com/groue/GRDB.swift.git, from: 6.0.0), .package(url: https://github.com/apple/swift-nio.git, from: 2.60.0), .package(url: https://github.com/jakeheis/SwiftCLI.git, from: 6.0.0)其中SwiftCLI是用来写一些命令行调试工具的比如发送一条测试消息、清空本地数据库之类。这比在 UI 里操作要快得多强烈推荐给所有做客户端项目的人准备几个 CLI 入口。4.2 首次启动与连接配置首次启动后点击“添加账号”输入 JID比如alicelocalhost和密码。点击连接时可以打开控制台日志看到完整的 XMPP 连接过程。正常的流程应该是类似下面的输出[colibri] Connecting to localhost:5222 [colibri] ✅ TCP connection established [colibri] TLS handshake completed [colibri] Opening XML stream... [colibri] ✅ Stream opened, server requires SASL authentication [colibri] Authenticating with SCRAM-SHA-1... [colibri] ✅ Authentication successful [colibri] Binding resource... (colibri-mac) [colibri] ✅ Bound resource, session started [colibri] Fetching roster... [colibri] ✅ Roster received (12 contacts)看到最后一行的 roster 接收完成说明连接流程没有任何问题。如果卡在TLS handshake completed之后大概率是服务器证书不受信任。ejabberd 默认是自签名证书需要在客户端的 TLS 配置里加一行信任策略let tlsOptions NWProtocolTLS.Options() sec_protocol_options_set_verify_block(tlsOptions.securityProtocolOptions, true) { _, _, complete in complete(.proceed) // 仅建议在本地开发时这么写 }这个“信任所有证书”的配置只适合开发环境生产环境绝对要证书校验否则很容易被中间人攻击。4.3 消息收发与本地落库验证连接成功后直接用命令行工具发一条消息验证链路swift run colibri-cli send --to boblocalhost --body Hello from colibri!这条命令会走完整的业务逻辑写入 outbox 表、建立 XMPP 消息节点、发送、等待服务端回执、更新消息状态。执行结束后可以去 SQLite 里确认sqlite3 ~/Library/Containers/com.colibri/Data/Documents/colibri.sqlite \ select * from messages order by timestamp desc limit 3;正常的输出会展示这条消息的status字段变成了sent说明对端服务器已经确认收到。此时在另一个终端登录 bob 的账号如果环境配置正确应该能看到 alice 发来的消息。这里有一个经验消息落库必须在发送前完成而不是发送成功后再写库。因为用户在点击发送的瞬间这条消息就应该立刻出现在聊天窗口里即使网络是断的否则会有明显的“卡了一下”的感觉。先写库、后发送、再更新的模式是聊天室体验流畅的关键。5. 常见问题与排查技巧实录5.1 连接层的高频问题做一个网络相关项目90%的问题都出在连接层。我把这段时间里遇到的典型问题整理了一下排名不分先后服务器主动断开流大多数情况是 XML 格式问题检查流头里的命名空间、是否有非法字符SASL 认证失败优先检查账号是否真的在服务器注册了其次检查 Base64 编码是否有多余字符TLS 握手失败本地开发最常见的原因是端口写错5222 vs 5223或者证书校验策略太严格roster 拉取为空检查是否登录了正确的 JID有人会不小心注册成alicelocalhost但登录时输入alice这通常会失败如果注册的是alicelocalhost登录时也要写全。5.2 本地数据库锁与多线程竞争SQLite 在多线程场景下有个经典问题如果一个连接在写库另一个线程去读库会报SQLITE_BUSY。我一开始直接用同一个 GRDB 的DatabaseQueue处理所有读写结果高并发时频繁报错。后来改成了DatabasePool读走一个连接、写走另一个连接写操作统一放进串行队列保证同一时刻只有一个写事务。如果你也在做一个需要后台线程频繁写库的 App建议一开始就用DatabasePool而不是DatabaseQueue。虽然前期的写入性能没有明显差别但到后期要加全文搜索、批量导入功能时并发读的优势就会显现出来。5.3 界面卡顿与“网红”主线程陷阱SwiftUI 开发中一个很隐蔽的坑是某些看似普通的调用其实发生在主线程。比如通知回调里更新数据库的fetch、改Published属性而没加MainActor这些操作叠加起来就会让 UI 偶发卡顿。我的排查工具是 Xcode 自带的 Thread Performance Checker 和 Instruments 的 Time Profiler。通过 profile 发现90% 的卡顿来自messages表的大范围查询。优化方案是加索引CREATE INDEX idx_messages_conversation_time ON messages(conversation_id, timestamp DESC);加了索引之后翻历史消息的耗时从平均 80ms 降到了 3ms 左右体感差距非常明显。这里也要特别提醒SwiftUI 的List虽然好用但在展示大量消息时会有性能瓶颈。最终我换成了ScrollView LazyVStack配合State控制滚动位置才能做到流畅翻看几千条历史记录。5.4 消息乱序的最终补救方案尽管我在设计阶段就考虑了乱序问题实际联调时还是遇到了消息乱序。原因出在“本地时间戳排序”和“会话列表的 last_message_time 排序”用到了两个不同的字段。后来我统一了排序原则会话列表排序用last_message_time服务器时间戳消息详情内的排序用local_order本地自增 ID。消息详情里的排序只依赖local_order彻底隔离了服务器时间对 UI 顺序的影响。这个修复给了我一个很大的启发任何时候UI 排序依据的字段必须来自同一个数据源不要混用“服务器时间”“本地时间”“序号”这三种维度。否则在极端情况下一定会出现难以察觉的顺序错乱。6. 踩坑与经验那些文档里不会明说的事6.1 三个最值得说的坑排名第一的坑是ejabberd 的默认证书配置。用 Docker 跑 ejabberd 时它的容器里同时生成了多个自签名证书客户端如果只信任其中一个域名很容易出现“证书匹配失败”。解决方案是在客户端日志里打印服务器的证书链查看subjectAltName是否包含你的服务器域名再决定校验策略。排名第二的坑是XMPP 的 resource 冲突。同一个账号在第二台设备登录时如果默认 resource 名字重复服务器会踢掉旧连接。我一度怀疑是代码问题调了一整天。后来才发现是 resource 前缀写死成colibri-mac第二台设备也是colibri-mac就会冲突。修复方案是加上 UUID 后缀比如colibri-mac-8f3c2a同时实现 XEP-0280消息回执让用户能感知到“消息已被另一台设备阅读”。排名第三的坑是SwiftUI 的State跨线程更新。收到消息的通知回调如果你直接修改State属性编译器不报错但 UI 不会刷新。正确做法是通知回调里只做Task { MainActor in ... }的调度确保所有 UI 状态修改都在主线程。6.2 给接手者的话这个项目的乐高积木都搭好了但还有一些地方值得继续打磨。如果你有兴趣接手我建议从以下三个方向入手iOS 端的后台推送目前只是留了 stub你可以基于 XEP-0357 写一个真正的 push gateway端到端加密XMPP 有 OMEMOXEP-0384标准可以基于 Signal 协议做双棘轮加密这个工作量不低但很有价值性能基准测试我写了一个简单的 benchmark 脚本但还没有形成完整的 CI 指标你可以把它接入 GitHub Actions每次提交都跑一遍内存和耗时测试。最后再说一个从这个项目里沉淀下来的实操习惯给网络层和存储层写独立的 CLI 工具。调试 UI 问题时你往往需要先把“数据是否正确”跑通才能去查“UI 为什么不显示”。有了 CLI 工具数据链路可以单独验证UI 的调试压力会小很多。我在这个项目上尝到了甜头后来做其他 App 也沿用了这个思路效率提升非常明显。如果你也想试着自己做一个轻量级 IM或者对 Swift 的客户端架构感兴趣我建议先把 colibri 仓库拉下来跑通一次消息收发再试着改一两个模块。动手实操一遍比看十遍文档都有用。