建立第一個 MQTT 連線
建立第一個 MQTT 連線：使用 EMQX 內建 WebSocket 測試工具與診斷頁 publish／subscribe，驗證 QoS，認識連線與訂閱的基本操作。
為什麼要學這個
你的 add-on 已經把 EMQX 5.8.9 跑起來，但你可能還沒「親眼」看過 MQTT 訊息真正走過 broker。第 4 章建立的都是紙上心智模型，這章就是填補「第一觸」的關鍵一步：用 EMQX 內建的 WebSocket 測試工具，在瀏覽器裡直接 publish 與 subscribe，發出訊息、再在同一個連線上收回來，也實際動手把它們在收到時分派的 QoS 差異看個清楚。
讀完之後，你手上會有一個「想確認 broker 到底通不通」的最快方法——不用安裝第三方程式、不用寫一行程式，就能驗證連線、主題、Payload與 QoS 的行為。後續每一章拿實機測試時，都會反覆回到這隻 WebSocket 工具。
核心概念
MQTT 是發布／訂閱（publish／subscribe）制：發布者把訊息依主題（topic）送出，訂閱者只訂閱自己有興趣的主題，所有訊息都由扮演伺服的 broker 路由。驗證這件事最直接的方式，就是開兩頭：一頭發布、一頭訂閱，看 broker 有沒有把訊息送到的「正確訂閱者」。
EMQX 提供多種工具可以做這件事：客戶端桌面的 MQTTX、命令列的 MQTTX CLI、瀏覽器版的 MQTTX Web，以及 EMQX Dashboard 內建的 WebSocket 客戶端。前幾種都要另外安裝或記工具，內建的那隻不用——它走「MQTT over WebSocket」、預設接連接埠 8083，直接在網頁裡完成 connect、subscribe、publish 三個動作，最適合作為你的「第一個」測試工具。
名詞對照
| 英文 | 中文 | 一句話 |
|---|---|---|
| Publish | 發布 | 把訊息送到某個主題（topic） |
| Subscribe | 訂閱 | 宣告想收到哪些主題的訊息 |
| Topic | 主題 | 訊息分類用的階層名稱 |
| Payload | 訊息內容 | 發布時實際攜帶的資料 |
| QoS | 服務品質等級 | 訊息傳遞的保證程度（0／1／2） |
| Retained | 保留訊息 | broker 記住最後一則，新訂閱者立刻收到 |
| WebSocket | 網頁套件通道 | 讓瀏覽器跑 MQTT 的傳輸方式 |
動手做
進到 WebSocket 客戶端
登入 EMQX Dashboard（帳號密碼第 2 章已改過就用你自己的）。左側選單點 Diagnose → WebSocket Client。
建立第一筆連線
在 Connection 區塊中 Host 維持
localhost（從別的裝置進來就改成你的 Home Assistant 位址），Port 維持8083；還沒建立驗證時 Username／Password 留空。按 Connect，狀態變成 Connected 就是成功。訂閱並發布
在 Subscription 區塊把 Topic 設成
testtopic/#，按 Subscribe。再到 Publish 區塊把 Topic 設testtopic/1、Payload 填{"msg":"Hello"}、QoS 先用0，按 Publish。下方 Received 區會出現同一則訊息，因為你同時也是訂閱者。驗證 QoS
把 Publish 的 QoS 改成
1（甚至2）再送一筆，觀察訊息一樣抵達 Received。體會「QoS 0 盡力送、QoS 1 至少一次、QoS 2 恰一次」在真實投遞上的差別，到下面「驗證 QoS」主題看三者的適用情境。
WebSocket 測試工具導覽
Diagnose 選單裡有幾個除錯工具：Alarms（警示）、WebSocket Client、Topic Monitoring（主題監控）、Slow Subscriptions（慢訂閱）與 Log Trace（日誌追蹤）。其中 Alarms、Topic Monitoring、Slow Subscriptions 是 EMQX Enterprise 付費版才有，Open Source 的 5.8.9 你實際只會用到 WebSocket Client 與 Log Trace——不必花時間在 Open Source 介面上找 Enterprise 才有的項目。
WebSocket Client 提供 connect、subscribe、publish 三段操作，也會顯示你自己送出的（Published）與收到的（Received）資料。你可以按 + 同時開多筆 WebSocket 連線，各自獨立。有個要注意的行為：只要重整這頁，所有連線與收發資料都會被清空——它是快速測試工具，不是存放連線歷史的地方。
還有一個要留心的坑：Publish 區塊的 Topic 不能帶 + 或 # 萬用字元，只有 Subscription 的主題才能用萬用字元。
驗證 QoS
QoS（Quality of Service，服務品質）是 MQTT 控制單則訊息「投遞保證程度」的機制。EMQX 兩頭都支援三種 QoS，在 WebSocket 工具的訂閱與發布都能選。
| QoS | 名稱 | 保證 | 典型情境 |
|---|---|---|---|
| 0 | 最多一次 | 不保證送達或重複 | 週期性感應器，輕量丟掉無妨 |
| 1 | 至少一次 | 保證送達，但可能重複 | 可接受一兩次重複的狀態變更 |
| 2 | 且只有一次 | 保證送達，且不重複 | 開關、控制指示，重複不可 |
測試時最省的方式，就是發布到一個你自己訂閱的主題：Publisher 與 Subscriber 是同一端時，broker 一樣會把訊息跨接路由回來，於是你可以在 Received 資料列裡親眼確認「QoS 改變後，收到的是不是同一筆、有沒有重複」。想再驗證 Retained（保留訊息），只要發布時勾 Retain，新加入的訂閱者立刻就可以收該主題最後一筆——它與 QoS 是兩件事，心智模型在第 4 章已建立。
故障排除
- Connect 沒反應或一直失敗：先確認 8083 有沒有被其他服務（如 WebRTC）佔用，這與第 2 章的連接埠衝突同源；若你是從別的裝置進來的，Host 必須填 Home Assistant 主機位址，不是
localhost。 - 訂閱了卻收不到訊息：檢查你的訂閱主題是否用萬用字元包住發布主題（如訂
testtopic/#才貼得到testtopic/1）。發布成功後 Received 區應該要有資料列，一條都沒看到就代表 broker 沒真的路由到。 - 收到的訊息重複出現：如果你發布選 QoS 1，重複是「至少一次」的正常結果；想精確只有一次就要選 QoS 2，不要以為是 broker 出了問題。
- 重整頁後連線資料全部消失：這是內建 WebSocket 工具的預設清除行為，不是 bug。若你要保存連線記錄、多組設定，改用桌面工具 MQTTX；它們適合作為持續測試的設備。
常見問題
內建 WebSocket 工具跟 MQTTX 差在哪
內建工具在 EMQX Dashboard 裡，不用安裝、最適合快速看訊；MQTTX（桌面／CLI／Web）功能更豐富，可以保存多組連線、支援更細的 MQTT 5.0 設定，適合持續除錯與開發。兩者通訊能力相同，沒有硬性要用哪一款。
為什麼測試用 8083，而不是 1883
內建工具是「瀏覽器直接在網頁裡跑 MQTT over WebSocket」的通道，走的是 8083；1883 是純 TCP 的 MQTT，瀏覽器不能直接連，要連 1883 得用桌面 MQTTX 或 CLI 等工具。兩者都是 MQTT，只是傳輸層方式不同。
QoS 0、1、2 我到底該選哪個
可丟掉的資料選 0；必須送出但可接受重複的選 1；不能重複的關鍵控制（如開關）選 2。先在三種之間都發布一次，看你在同一個連線收到時的差異，再依實際情境挑選。
工具能同時開多個連線嗎
可以。按 + 可以同時開多支 WebSocket Client，各自有獨立的連線狀態與收發資料列。你若想模擬「publisher 與 subscriber 各一篇」，開兩支連線分別做訂閱與發布會更方便。