## 簡介

[MQTT.js](https://github.com/mqttjs/MQTT.js) 是一個開源的 [MQTT 協議](https://www.emqx.com/zh/mqtt)的客戶端庫，使用 JavaScript 編寫，主要用於 Node.js 和 瀏覽器環境中。是目前 JavaScript 生態中使用最為廣泛的 [MQTT 客戶端庫](https://www.emqx.com/zh/blog/introduction-to-the-commonly-used-mqtt-client-library)。

> MQTT 是一種基於釋出/訂閱模式的輕量級物聯網訊息傳輸協議，可以用極少的程式碼和頻寬為聯網裝置提供實時可靠的訊息服務，它廣泛應用於物聯網、移動網際網路、智慧硬體、車聯網、電力能源等行業。

由於 JavaScript 單執行緒特性，MQTT.js 是全非同步 MQTT 客戶端，MQTT.js 支援 MQTT/TCP、MQTT/TLS、MQTT/WebSocket，在不同執行環境支援的度如下：

- 瀏覽器環境：MQTT over WebSocket（包括微信小程式、支付寶小程式等定製瀏覽器環境）
- Node.js 環境：MQTT、MQTT over WebSocket

不同環境裡除了少部分連線引數不同，其他 API 均是相同的。且在 MQTT.js v3.0.0 及以上版本後，已經完整支援到 MQTT 5.0。

## 安裝

### 使用 npm 或 yarn 安裝

```shell
npm install mqtt --save

# 或使用 yarn

yarn add mqtt
```

**注意**：如果您的 Node 環境是 v12 或 v14 及以上版本，請使用 MQTT.js 4.0.0 及以上版本

### 使用 CDN 安裝

在瀏覽器環境中，我們還可以使用 CDN 的方式引入 MQTT.js。MQTT.js 的 bundle 包透過 [http://unpkg.com](http://unpkg.com/) 管理，我們可以直接新增 [unpkg.com/mqtt/dist/mqtt.min.js](https://unpkg.com/mqtt/dist/mqtt.min.js) 來進行使用。

```html
<div></div>
<div>
  // 將在全域性初始化一個 mqtt 變數
  console.log(mqtt)
</div>
```

### 全域性安裝

除了上述的安裝方式外，MQTT.js 還提供了全域性安裝的方式，使用命令列工具來完成 MQTT 的連線、釋出和訂閱等。

```shell
npm install mqtt -g
```

我們會在下文中的一些使用教程中詳細描述如何使用 MQTT.js 的命令列工具。

## 使用

本文將使用 EMQ X Cloud 提供的 [免費公共 MQTT 伺服器](https://www.emqx.com/zh/mqtt/public-mqtt5-broker) 作為本次測試的 MQTT 伺服器地址，伺服器接入資訊如下：

- Broker: **broker.emqx.io**
- TCP Port: **1883**
- SSL/TLS Port: **8883**

更多詳情請訪問 [EMQ X Cloud 官網](https://www.emqx.com/zh/cloud)，或檢視 [EMQ X Cloud 文件](https://docs.emqx.cn/cloud/latest/)。

### 簡單例子

我們簡單編寫一段程式碼實現連線到 EMQ X Cloud 的並完成訂閱主題、收發訊息的例子：

```javascript
const mqtt = require('mqtt')
const options = {
  // Clean session
  clean: true,
  connectTimeout: 4000,
  // Auth
  clientId: 'emqx_test',
  username: 'emqx_test',
  password: 'emqx_test',
}
const client  = mqtt.connect('mqtt://broker.emqx.io:1883')
client.on('connect', function () {
  console.log('Connected')
  client.subscribe('test', function (err) {
    if (!err) {
      client.publish('test', 'Hello mqtt')
    }
  })
})

client.on('message', function (topic, message) {
  // message is Buffer
  console.log(message.toString())
  client.end()
})
```

### 命令列

在全域性安裝完 MQTT.js 後，我們同樣可以使用命令列工具來完成主題訂閱訊息釋出接收的動作。

示例連線到 `broker.emqx.io` 並訂閱 `testtopic/#` 主題：

```shell
mqtt sub -t 'testtopic/#' -h 'broker.emqx.io' -v
```

示例連線到 `broker.emqx.io` 並向 `testtopic/hello` 主題傳送訊息

```shell
mqtt pub -t 'testtopic/hello' -h 'broker.emqx.io' -m 'from MQTT.js'
```

### API 介紹

#### mqtt.connect([url], options)

連線到指定的 MQTT Broker 的函式，並始終返回一個 Client 物件。第一個引數傳入一個 URL 值，URL 可以是以下協議：`mqtt`, `mqtts`, `tcp`, `tls`, `ws`, `wss`。URL 也可以是一個由 URL.parse() 返回的物件。然後再傳入一個 Options 物件，用於配置 MQTT 連線時的選項。下面列舉一些常用的 Options 物件中的屬性值：

- Options
  - `keepalive`: 單位為`秒`，數值型別，預設為 60 秒，設定為 0 時禁止
  - `clientId`: 預設為 `'mqttjs_' + Math.random().toString(16).substr(2, 8)`，可以支援自定義修改的字串
  - `protocolVersion`: MQTT 協議版本號，預設為 4（v3.1.1）可以修改為 3（v3.1）和 5（v5.0）
  - `clean`: 預設為 `true`，是否清除會話。當設定為 `true` 時，斷開連線後將清除會話，訂閱過的 Topics 也將失效。當設定為 `false` 時，離線狀態下也能收到 QoS 為 1 和 2 的訊息
  - `reconnectPeriod`: 重連間隔時間，單位為毫秒，預設為 1000 毫秒，**注意：**當設定為 0 以後將取消自動重連
  - `connectTimeout`: 連線超時時長，收到 CONNACK 前的等待時間，單位為毫秒，預設 30000 毫秒
  - `username`: 認證使用者名稱，如果 Broker 要求使用者名稱認證的話，請設定該值
  - `password`: 認證密碼，如果 Broker 要求密碼認證的話，請設定該值
  - `will`: 遺囑訊息，一個可配置的物件值，當客戶端非正常斷開連線時，Broker 就會向遺囑 Topic 裡面釋出一條訊息，格式為：
    - `topic`: 遺囑傳送的 Topic
    - `payload`: 遺囑釋出的訊息
    - `QoS`: 遺囑傳送的 QoS 值
    - `retain`: 遺囑釋出的訊息的 retain 標誌
  - `properties`: [MQTT 5.0](https://www.emqx.com/zh/mqtt/mqtt5) 新增，可配置的物件的屬性值，詳情請參考：[https://github.com/mqttjs/MQTT.js#mqttclientstreambuilder-options](https://github.com/mqttjs/MQTT.js#mqttclientstreambuilder-options)

- 如果需要配置 SSL/TLS 連線，Option 物件會被傳遞給 [`tls.connect()`](http://nodejs.org/api/tls.html#tls_tls_connect_options_callback) ，因此可以在 option 中配置以下屬性
  - `rejectUnauthorized`: 是否驗證服務端證照鏈和地址名稱，設定為 false 時將跳過驗證，會暴露在中間人的攻擊之下，所以不建議在生產環境中使用這種配置，當設定為 true 時，將開啟強認證模式，且如果是自簽名證照，請在證照配置時設定 Alt name。
  - `ca`:  只有在伺服器使用自簽名證照時才有必要，自簽名證照中生成的 CA 檔案
  - cert: 只有當伺服器需要客戶證照認證時才有必要（雙向認證），客戶端證照
  - key: 只有當伺服器需要客戶證照認證時才有必要（雙向認證），客戶端金鑰

#### Client 事件

當連線成功後，返回的 Client 物件可透過 on 方法監聽多個事件，業務邏輯可在監聽的回撥函式中完成。以下列舉一些常用的事件：

- `connect`

當連線成功時觸發，引數為 connack

```javascript
  client.on('connect', function (connack) {
    console.log('Connected')
  })
  ```

- `reconnect`

當斷開連線後，經過重連間隔時間重新自動連線到 Broker 時觸發

```javascript
  client.on('reconnect', function () {
    console.log('Reconnecting...')
  })
  ```

- `close`

在斷開連線以後觸發

```javascript
  client.on('close', function () {
    console.log('Disconnected')
  })
  ```

- `disconnect`

在收到 Broker 傳送過來的斷開連線的報文時觸發，引數 packet 即為斷開連線時接收到的報文，MQTT 5.0 中的功能

```javascript
  client.on('disconnect', function (packet) {
    console.log(packet)
  })
  ```

- `offline`

當客戶端下線時觸發

```javascript
  client.on('offline', function () {
    console.log('offline')
  })
  ```

- `error`

當客戶端無法成功連線時或發生解析錯誤時觸發，引數 error 為錯誤資訊

```javascript
  client.on('error', function (error) {
    console.log(error)
  })
  ```

- `message`

當客戶端收到一個釋出過來的 Payload 時觸發，其中包含三個引數，topic、payload 和 packet，其中 topic 為接收到的訊息的 topic，payload 為接收到的訊息內容，packet 為 MQTT 報文資訊，其中包含 QoS、retain 等資訊

```javascript
  client.on('message', function (topic, payload, packet) {
    // Payload is Buffer
    console.log(`Topic: ${topic}, Message: ${payload.toString()}, QoS: ${packet.qos}`)
  })
  ```

#### Client 方法

Client 除監聽事件外，也內建一些方法，用來進行釋出訂閱的操作等，以下列舉一些常用的方法。

- `Client.publish(topic, message, [options], [callback])`

向某一 topic 釋出訊息的函式方法，其中包含四個引數：

- topic: 要傳送的主題，為字串
  - message: 要傳送的主題的下的訊息，可以是字串或者是 Buffer
  - options: 可選值，釋出訊息時的配置資訊，主要是設定釋出訊息時的 QoS、Retain 值等。
  - callback: 釋出訊息後的回撥函式，引數為 error，當釋出失敗時，該引數才存在

```javascript
  // 向 testtopic 主題傳送一條 QoS 為 0 的測試訊息
  client.publish('testtopic', 'Hello, MQTT!', { qos: 0, retain: false }, function (error) {
    if (error) {
      console.log(error)
    } else {
      console.log('Published')
    }
  })
  ```

- `Client.subscribe(topic/topic array/topic object, [options], [callback])`

訂閱一個或者多個 topic 的方法，當連線成功需要訂閱主題來獲取訊息，該方法包含三個引數：

- topic: 可傳入一個字串，或者一個字串陣列，也可以是一個 topic 物件，`{'test1': {qos: 0}, 'test2': {qos: 1}}`
  - options: 可選值，訂閱 Topic 時的配置資訊，主要是填寫訂閱的 Topic 的 QoS 等級的
  - callback: 訂閱 Topic 後的回撥函式，引數為 error 和 granted，當訂閱失敗時 error 引數才存在, granted 是一個 {topic, qos} 的陣列，其中 topic 是一個被訂閱的主題，qos 是 Topic 是被授予的 QoS 等級

```javascript
  // 訂閱一個名為 testtopic QoS 為 0 的 Topic
  client.subscribe('testtopic', { qos: 0 }, function (error, granted) {
    if (error) {
      console.log(error)
    } else {
      console.log(`${granted[0].topic} was subscribed`)
    }
  })
  ```

- `Client.unsubscribe(topic/topic array, [options], [callback])`

取消訂閱單個主題或多個主題，該方法包含三個引數：

- topic: 可傳入一個字串或一個字串陣列
  - options: 可選值，取消訂閱時的配置資訊
  - callback: 取消訂閱時的回撥函式，引數為 error，當取消訂閱失敗時 error 引數才存在

```javascript
  // 取消訂閱名為 testtopic 的 Topic
  client.unsubscribe('testtopic', function (error) {
    if (error) {
      console.log(error)
    } else {
      console.log('Unsubscribed')
    }
  })
  ```

- `Client.end([force], [options], [callback])`

關閉客戶端，該方法包含三個引數:

- force: 設定為 true 時將立即關閉客戶端，而無需等待斷開連線的訊息被接受。這個引數是可選的，預設為 false。**注意**：使用該值為 true 時，Broker 無法接收到 disconnect 的報文
  - options: 可選值，關閉客戶端時的配置資訊，主要是可以配置 reasonCode，斷開連線時的 Reason Code
  - callback: 當客戶端關閉時的回撥函式

```javascript
  client.end()
  ```

## 總結

至此就簡單的介紹了 MQTT.js 一些常用的 API 的使用方法等，具體在實際專案中的使用請參考以下連結：

- [如何在 Vue 專案中使用 MQTT](https://www.emqx.com/zh/blog/how-to-use-mqtt-in-vue)
- [如何在 React 專案中使用 MQTT](https://www.emqx.com/zh/blog/how-to-use-mqtt-in-react)
- [如何在 Electron 專案中使用 MQTT](https://www.emqx.com/zh/blog/how-to-use-mqtt-in-electron)
- [如何在 Node.js 專案中使用 MQTT](https://www.emqx.com/zh/blog/how-to-use-mqtt-in-nodejs)
- [使用 WebSocket 連線 MQTT 伺服器](https://www.emqx.com/zh/blog/connect-to-mqtt-broker-with-websocket)

>版權宣告： 本文為 EMQ 原創，轉載請註明出處。
>
>原文連結：[https://www.emqx.com/zh/blog/mqtt-js-tutorial](https://www.emqx.com/zh/blog/mqtt-js-tutorial)
>
>技術支援：如對本文或 EMQ 相關產品有疑問，可訪問 EMQ 問答社群 [https://askemq.com](https://askemq.com) 提問，我們將會及時回覆支援。
>
>更多技術乾貨，歡迎關注我們公眾號【EMQ 中文社群】。

MQTT.js 入門教程

相關文章