uni-app MQTT 真机调试踩坑记录

面向小白：从项目搭建到 H5/App 双端 MQTT 通信，再到真机常见坑排查与 UI 设计说明。服务器信息已打码。

---

1. 项目背景与目标

做一个基于 uni-app 的 MQTT 控制小应用，目标功能：

• 三端统一：H5 + App（Android）可用
• 三页结构：首页 / 历史 / 设置
• 基础通信：连接、订阅、发布、历史记录
• 真机稳定：解决 WebSocket、编码、Android 限制问题

---

2. 项目结构与目录说明

E:/LED
├─ pages/
│  ├─ index/index.vue        # 首页（连接状态 + LED 控制 + 设备信息）
│  ├─ history/index.vue      # 历史消息（IN/OUT）
│  └─ profile/index.vue      # 连接配置
├─ utils/
│  ├─ mqtt-client.js         # MQTT 客户端（H5 mqtt.js + App socket）
│  ├─ mqtt-config.js         # 默认连接配置
│  └─ mqtt-history.js        # 本地消息历史
├─ static/                   # TabBar 图标等静态资源
├─ manifest.json             # App 配置/权限
└─ pages.json                # 页面 + tabBar

---

3. MQTT 连接参数（打码）

Host: ***.***.***.***
WS 端口: 8083
Path: /mqtt
用户名: adm***
密码: lo***

注意： 1883 是 TCP 端口，真机 App 不能直连。必须使用 WebSocket（ws/wss）。

---

4. 依赖安装与运行步骤

4.1 安装依赖

npm install

依赖：

• mqtt（H5 使用）
• @dcloudio/uni-ui（基础组件）

4.2 运行 H5

在 HBuilderX 里运行到 H5 或使用命令：

npm run dev:h5

（如果没有脚本，请在 HBuilderX 中运行）

4.3 运行 App（Android）

• HBuilderX → 运行 → 运行到手机/模拟器
• 首次真机建议勾选“清理缓存”

---

5. H5 / App 双端实现核心代码

5.1 H5 端：mqtt.js

const client = mqtt.connect('ws://host:port/mqtt', {
  username,
  password,
  clientId
})

5.2 App 端：uni.connectSocket

socketTask = uni.connectSocket({
  url: 'ws://host:port/mqtt',
  protocols: ['mqtt'] // 必须！
})

App 端使用 socket 自行拼装 MQTT 报文，实现 CONNECT / SUBSCRIBE / PUBLISH。

---

6. 真机调试 3 大坑（重点）

6.1 TextEncoder / TextDecoder 报错

现象：

ReferenceError: TextEncoder is not defined
ReferenceError: TextDecoder is not defined

原因：App 真机环境没有标准 Web API。
解决：在 mqtt-client.js 里实现 UTF-8 编解码 fallback。

---

6.2 连接失败但无错误

原因：缺少 protocols: ['mqtt']，Broker 会拒绝握手。
解决：补上协议字段。

---

6.3 Android 9+ 明文 ws 连接失败

原因：系统默认禁止明文 ws。
解决：放行网络权限。

manifest.json：

"networkSecurityConfig": "network_security_config"

network_security_config.xml：

<network-security-config>
  <base-config cleartextTrafficPermitted="true">
    <trust-anchors>
      <certificates src="system" />
    </trust-anchors>
  </base-config>
</network-security-config>

---

7. UI 设计说明

首页

• 连接状态卡片
• 设备状态信息（在线、IP、RSSI）
• LED 控制按钮（开/关/切换/闪烁）

历史页

• IN/OUT 方向过滤
• JSON 自动展开显示

个人中心

• 配置协议、Host、Port、Path
• 保存后自动重连

设计风格：卡片 + 渐变背景 + 状态标签，提高可读性。

---

8. 常见错误排查清单

1. 是否用 WebSocket 端口（8083，而不是 1883）
2. URL 是否包含 /mqtt
3. protocols: ['mqtt'] 是否添加
4. Android 是否允许明文 ws
5. MQTTX Web 是否能连接同一地址

---

9. 截图

9.1 首页

9.2 历史

9.3 设置中心

---

10. 总结

这次最重要的经验就是：

• 真机必须用 WebSocket
• 必须带 protocols: ['mqtt']
• Android 9+ 必须放行明文 ws

只要这三点搞定，MQTT 真机连接基本稳了。

---

如果你也踩坑了，可以留言交流。