Socket.IO 錯誤訊息通常是在描述連線為什麼結束，而不是一定代表程式 bug。`ping timeout` 多半是心跳逾時，`transport close` 常見於頁面關閉或網路中斷，namespace disconnect 則通常是 client 或 server 主動斷線。
`ping timeout` 是什麼意思？
`ping timeout` 代表 client 在 `pingTimeout` 允許時間內沒有回應 pong。常見原因包含網路中斷、瀏覽器背景節流、行動網路切換或 client 主執行緒被長任務卡住。
排查方向：
| 檢查項目 | 說明 |
|---|---|
| `pingInterval` | server 發送 ping 的頻率 |
| `pingTimeout` | 等待 pong 的最長時間 |
| client 主執行緒 | 長任務可能讓 pong 延遲 |
| 行動網路 | Wi-Fi 與 4G 切換可能造成短暫斷線 |
| proxy timeout | 中間層可能提早關閉閒置連線 |
若 `ping timeout` 偶發出現在手機或背景分頁，不一定是 server 異常。若大量 client 同時出現，應檢查 proxy、部署或網路事件。
`transport close` 是什麼意思？
`transport close` 表示底層 transport 被關閉。使用者關閉分頁、重新整理、網路品質差、proxy 關閉連線，或 server 重啟都可能造成這個訊息。
原始討論指出，關閉或 reload 頁面時會看到 `transport close`；網路狀況不好、ping packet 沒有送達 client 時也可能發生。
資訊增益：`transport close` 不適合單獨拿來判斷「使用者主動離開」。若產品需要區分關頁與斷網，應搭配前端 `beforeunload`、server reconnect window 與最後活動時間判斷。
namespace disconnect 類錯誤代表什麼？
namespace disconnect 通常表示 Socket.IO namespace 層級的主動斷線。client 呼叫 `disconnect()` 和 server 呼叫 `socket.disconnect()`，會產生不同訊息。
常見訊息：
| 訊息 | 意義 |
|---|---|
| `client namespace disconnect` | client 呼叫 `client.disconnect()` |
| `server namespace disconnect` | server 呼叫 `socket.disconnect()` |
| `io server disconnect` | server 端斷開連線，常見於驗證失敗 |
如果驗證 middleware 判定 token 無效，server 可能主動斷線。這種情境應在 client 顯示登入過期或重新登入提示，而不是無限重連。
`transport error` 是什麼意思？
`transport error` 是底層傳輸發生錯誤的統稱。可能原因包含 WebSocket 握手失敗、代理設定錯誤、TLS 問題、CORS 錯誤或網路中斷。
排查順序：
- 檢查瀏覽器 Network 的 WebSocket request。
- 確認 HTTP status code 與 response header。
- 檢查 Nginx 或負載平衡器是否轉發 upgrade header。
- 比對 server log 的 socket id 與錯誤時間。
- 檢查 CORS、Cookie、認證 token 與 sticky session。
`transport error` 的資訊太泛，不能只靠錯誤字串下結論。需要同時看 client log、server log 與 proxy log。
Socket.IO 錯誤要如何記錄才好查？
Socket.IO 斷線紀錄應包含 socket id、user id、namespace、transport、reason、時間與目前網路環境。缺少這些欄位時，後續只能猜測原因。
建議紀錄欄位：
| 欄位 | 用途 |
|---|---|
| `socket.id` | 對應單次連線 |
| `userId` | 對應使用者 |
| `reason` | Socket.IO 斷線原因 |
| `transport` | polling 或 websocket |
| `namespace` | 哪個 namespace 斷線 |
| `connectedAt` | 連線存活時間 |
| `serverInstance` | 多後端時定位分流問題 |
這些欄位能幫助區分程式錯誤、使用者離開、網路波動與部署問題。
常見問題
`ping timeout` 是 server 壞掉嗎？
不一定。`ping timeout` 只代表心跳逾時，可能是 client 端網路、背景分頁節流或 proxy timeout。
`transport close` 可以當作使用者關閉網頁嗎？
不能完全當作。關頁會造成 `transport close`，但網路中斷與 proxy 關閉連線也可能造成同樣訊息。
`client namespace disconnect` 是錯誤嗎？
通常不是。這表示 client 主動呼叫 disconnect，可能是正常登出、切換頁面或程式主動關閉連線。
`io server disconnect` 後 client 會自動重連嗎？
依 Socket.IO 行為與 client 設定而定。若 server 主動斷線是因驗證失敗，應先更新 token 或重新登入。
Socket.IO 斷線要怎麼避免誤判？
不要只看 reason 字串。應同時記錄使用者操作、網路狀態、transport、server instance 與 reconnect 結果。
參考資料
- Socket.IO Docs：Server socket instance
- Socket.IO Docs：Client socket instance
- GitHub Issue：socket.io issue 3101
最後更新
本文最後更新於 2026-08-27。原文發布於 2020-03-16，本文把錯誤訊息整理成排查表，並補上紀錄欄位建議。
延伸閱讀
關於作者 {#author}
Claire Chang ｜ 企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。
首次發布：2020-03-16