訊息傳不出去？系統化排查即時通訊訊息傳送失敗原因的三個層面

排查即時通訊訊息傳送失敗原因時，第一步不是檢查網路，而是確認失敗形態。傳送失敗通常只有兩類：即時錯誤——呼叫介面立刻回傳錯誤碼、逾時或異常；假成功——訊息在本機顯示已傳送，但對方收不到或延遲很久。前者優先查端側狀態和連線層；後者大機率在伺服器端的儲存、路由或策略。

下面按「端側—連線層—伺服器端」三層推進。

先用兩個現象判斷故障層：即時錯誤 vs 假成功

• 即時錯誤：傳送請求立即回傳 401、403、413 或網路逾時。優先查看 SDK 初始化狀態、Token 權限與訊息主體限制。
• 假成功：本端傳送完成，其他端收不到。優先查看伺服器端離線訊息儲存、佇列積壓與策略命中。

層面一：端側傳送失敗——SDK 初始化、Token 與訊息格式

傳送動作在離開裝置前就可能失敗，多數是設定問題而非網路問題。逐項核對下列項目：

• SDK 未完成初始化或 init 回呼未回傳成功，就直接呼叫傳送介面，會得到「未初始化」或 -1 一類錯誤。
• Token 過期或權限不足。回傳 401/403 時，先查看伺服器端 token 有效期間和目前使用者權限，不要急著改網路。
• 訊息主體超過限制。文字長度、圖片大小或自訂欄位超過伺服器端限制，常見回傳碼為 413 或 400。
• 自訂訊息格式不符。擴充欄位型別與通訊協定定義不一致，會導致序列化失敗。
• 本機網路攔截。企業防火牆或安全軟體可能封鎖到訊息閘道的請求，可用最小請求重現判斷。

層面二：連線層「假上線」——長連線中斷、心跳與重連

介面顯示線上不等於長連線真正可用。很多「發不出去」是連線半開或被靜默斷開，傳送端仍在往一個失效連線寫入資料。

• 心跳間隔不合理。伺服器端已判定連線逾時並回收，用戶端卻仍顯示線上。
• 網路切換後未重連。從 Wi-Fi 切到行動網路時，舊連線沒有及時釋放，新的傳送請求被掛起。
• App 被系統背景終止。長連線斷開後沒有重建，回到前景時仍顯示舊狀態。
• TLS 憑證驗證失敗。私有化環境使用自簽憑證時，用戶端可能靜默斷開。

判斷標準不是看 App 頂部狀態，而是抓包確認是否還有心跳上行，或查看用戶端重連日誌裡是否有 reconnect 失敗記錄。

層面三：伺服器端策略與儲存——訊息被丟棄、限制或風控攔截

到了伺服器端但對方收不到，通常不是訊息沒進系統，而是被儲存策略、路由規則或風控邏輯攔下。

• 離線訊息未儲存或儲存失敗。接收方上線後拉不到歷史，可參考離線訊息收不到的常見原因與修復。
• 訊息佇列積壓。伺服器端已接收但投遞執行緒來不及處理，表現為延遲而非立即失敗。
• 頻率限制觸發。同一用戶短時間大量傳送，觸發限流後訊息被靜默丟棄。
• 敏感詞或風控策略誤攔。命中策略後不返回錯誤，訊息直接不投遞。
• 多端同步覆蓋。新訊息被舊訊息的同步動作覆蓋，導致部分端看到「已傳送」但內容缺失。

處理時先查伺服器端日誌中的訊息狀態、佇列深度和策略命中記錄，不要只盯客戶端錯誤碼。