简介：面向使用 MIT App Inventor 进行可视化编程的初学者与物联网爱好者，这份 UrsAI2Paho 扩展包提供了一套可直接导入的 MQTT 插件方案，解决 App Inventor 原生积木难以接入 MQTT 服务器、实现设备间发布订阅通信的问题。压缩包共 139 个文件，以 107 个 java 源码和 16 个 properties 配置为主，辅以 html 说明文档、aia 示例工程及 aix 插件本体，另含 pem、cer、bks 等证书文件，整体约 2.16MB，兼顾二次开发与直接使用。资源围绕连接与断开、发布与订阅、QoS 等级设置、消息事件处理及心跳维持等核心能力展开，并附带多个示例工程，便于读者对照理解插件在智能家居、环境监测等场景中的实际用法。目前已有 605 人学习，适合希望低成本将 App Inventor 应用接入物联网的开发者参考实践。
1. 装 APP Inventor 的 MQTT 扩展，先别急着点导入
上周帮一个做物联网课设的开发者收拾烂摊子：他在 APP Inventor 里导入 UrsAI2Paho 扩展包，界面直接白屏，重进项目连原来的块都加载不出来。这类翻车在 MQTT 插件扩展上特别常见——APP Inventor 本身是云端拼块环境，扩展包不是普通文件，导入路径、组件版本、浏览器缓存任何一环对不上，都会让项目变成打不开的黑匣子。UrsAI2Paho 是给 APP Inventor 补上 MQTT 通信能力的扩展，让拼块应用能连 Broker 收发消息，适合做物联网 Demo、传感器面板、远程控制这类原型。这篇按我实际装过的顺序写：环境先列清，再一步步导入配置，最后落到怎么验证真的连上了。
2. 环境准备：APP Inventor 版本与 UrsAI2Paho 扩展包的匹配
2.1 先确认你用的是哪套 APP Inventor
APP Inventor 有几个发行分支，扩展包能不能导入，第一道门槛就在这里。常见做法是先确认自己登录的是哪套服务：不同分支对扩展（Extension）的支持程度不一样，有的分支对 .aix 扩展的加载策略更宽松，有的则限制较多。我一般会先做三件事：确认当前项目是新建的还是从旧项目复制来的、确认浏览器是 Chrome 或 Edge 的较新版本、确认账号下没有同时开着多个编辑器标签页。这三件事看着琐碎，但后面导入失败时能帮你快速排除一半变量。
版本选择上没有太多花活：UrsAI2Paho 这类 Paho 系 MQTT 扩展，本质是把 Eclipse Paho 的 MQTT 客户端能力封装成 APP Inventor 可调用的组件。你不需要在本机装 Paho 的库，也不需要配 Java 环境，扩展包本身就是打包好的 .aix 文件。真正要留意的是 APP Inventor 侧对扩展的兼容窗口——如果你的编辑器版本较老，导入时可能提示扩展不受支持，这时候优先升级编辑器所在的环境，而不是去改扩展包。
2.2 扩展包与 Broker 侧的前置清单
装扩展之前，Broker 这头要先能通。我习惯先把 Broker 的连接参数写成一张小表，导入扩展后直接照着填，避免在拼块界面里反复试错。
| 参数项 | 说明 | 常见取值示例 |
|---|---|---|
| Broker 地址 | MQTT 服务的主机名或 IP | 局域网内自建服务地址 |
| 端口 | MQTT 明文端口或加密端口 | 明文常用 1883，加密常用 8883 |
| Client ID | 客户端唯一标识 | 自定义前缀加随机串 |
| 用户名/密码 | Broker 开启认证时必填 | 按 Broker 配置填写 |
| 订阅主题 | 应用要接收的消息主题 | 按业务自定义层级 |
| 发布主题 | 应用要发送的消息主题 | 与订阅主题区分开 |
这张表不是摆设。后面在扩展组件里填参数时，Client ID 重复是最容易被忽略的坑——两个设备用同一个 Client ID 连同一个 Broker，会互相把对方踢下线，现象是“一会儿能收一会儿不能收”，特别像玄学。我一般给 Client ID 加设备或时间后缀，保证唯一。
2.3 导入前的项目备份
导入扩展前，先把当前项目做一份副本。APP Inventor 的项目是云端保存的，但扩展导入失败有可能让项目进入异常状态，副本是唯一的后悔药。操作上就是项目菜单里复制一份，命名带日期。这一步花不了一分钟，但真出事时能救命。备份完再确认浏览器没有开无痕模式——无痕模式下部分本地缓存行为不同，导入扩展时偶发加载不全。
3. 导入 UrsAI2Paho 扩展：从 .aix 到组件面板
3.1 导入 .aix 扩展包的具体操作
导入入口在编辑器左侧的组件面板区域，找到扩展（Extension）相关的导入入口，选择本地的 UrsAI2Paho 扩展文件。导入成功后，组件面板里会多出一个对应的扩展分组，里面能看到这个扩展提供的组件。整个过程不需要命令行，但有几个细节决定成败。
操作顺序（在 APP Inventor 编辑器内）： 1. 打开目标项目，确认处于设计视图（Designer） 2. 左侧面板找到 Extension 导入入口 3. 选择本地 UrsAI2Paho 的 .aix 文件 4. 等待导入完成提示，不要中途刷新页面 5. 导入成功后检查组件面板是否出现新分组这段流程里最关键的是第 4 步。导入 .aix 时编辑器会在后台解析扩展描述文件，网络慢的时候进度条会停一会儿，很多人以为卡死就刷新页面，结果扩展只导入了一半，组件面板出现空分组或者干脆不出现。我的习惯是导入时不动页面，等提示明确出现再操作。如果超过一两分钟没有任何反馈，先看浏览器开发者工具的网络面板有没有失败请求，再决定是否重试。
导入完成后，把扩展组件拖到屏幕上，右侧属性面板会出现这个组件的可配置项。不同版本的扩展属性命名可能有差异，但核心就那几组：Broker 地址、端口、Client ID、认证信息、订阅与发布相关设置。拖组件这一步本身不报错，真正的配置问题都在下一步。
3.2 组件属性与连接参数的对应关系
把扩展组件拖进屏幕后，属性面板里的字段要和 2.2 那张表一一对上。我一般按“先填连接、再填主题、最后填认证”的顺序来，因为连接参数错了，后面填什么都白搭。
属性填写顺序建议： BrokerHost -> 填 Broker 地址，不带 mqtt:// 前缀 BrokerPort -> 填端口，明文 1883 / 加密 8883 ClientId -> 唯一标识，建议加随机后缀 Username -> Broker 开启认证时填写 Password -> 与用户名配套 SubscribeTopic -> 订阅主题，支持层级用斜杠分隔 PublishTopic -> 发布主题，与订阅主题分开这里有个参数取舍要讲清楚：端口和加密方式是绑定的。填 1883 走明文，填 8883 一般对应加密连接，但加密连接还需要 Broker 侧证书配置正确，否则连接会失败在握手阶段。做课设或内网 Demo，常见做法是先用明文端口把链路跑通，确认收发正常后再切加密端口，这样排错时能分清是“MQTT 逻辑问题”还是“证书问题”。另外 BrokerHost 不要带协议前缀，填了mqtt://反而可能解析失败，这是很多人从其他 MQTT 客户端迁移过来时顺手带进来的习惯。
主题设计也值得多说一句。订阅主题和发布主题最好分开，比如订阅用demo/device/command，发布用demo/device/status，避免自己发的消息被自己订阅回来形成回环。如果确实要自发自收做测试，至少加个消息内容判断，别让应用对自己的消息做出反应。
3.3 拼块逻辑：连接、订阅、收发的块组合
属性填完只是静态配置，真正让 MQTT 跑起来的是拼块逻辑。UrsAI2Paho 扩展提供的块大致分几类：连接与断开、订阅与取消订阅、发布消息、连接状态与消息到达事件。我一般按“连接成功后再订阅”的顺序拼，不要在连接还没建立时就调订阅，否则订阅请求可能丢失。
拼块逻辑骨架（按执行顺序）： 当 屏幕初始化 -> 调用 扩展.连接 当 扩展.连接成功（事件） -> 调用 扩展.订阅(SubscribeTopic) 当 扩展.消息到达（事件） -> 读取 主题 与 消息内容 -> 按主题分支处理业务 当 按钮点击（发布场景） -> 调用 扩展.发布(PublishTopic, 消息内容) 当 屏幕关闭 -> 调用 扩展.断开连接这段骨架里有两个容易漏的点。第一是断开连接：很多 Demo 只在初始化时连，退出时不主动断，Broker 侧会残留会话，下次用同一个 Client ID 连可能被拒或延迟。第二是消息到达事件里的主题判断：如果订阅了多个主题，一定要按主题分支处理，否则不同格式的消息混在一起解析，出错时很难定位。发布消息时消息内容建议先拼成固定格式（比如 JSON 字符串），接收端解析才有稳定预期。
4. 避坑与排查：导入失败、连不上、收不到消息
4.1 导入 .aix 后组件面板没有新分组
现象：导入提示完成，但组件面板找不到扩展组件，或者分组是空的。原因通常是导入过程中页面被刷新或网络中断，扩展描述文件没解析完整；也可能是当前编辑器分支对扩展支持有限。解决：先刷新编辑器重新进入项目看分组是否出现，仍不出现就删掉项目里的异常扩展记录重新导入，导入时保持页面不动。如果多次失败，换一个浏览器或确认编辑器版本是否过老。
4.2 连接一直失败，日志里没有明确原因
现象：点连接后状态一直不是已连接，也没有报错弹窗。原因多半在参数：BrokerHost 带了协议前缀、端口和加密方式不匹配、Client ID 与在线设备重复。解决：按 2.2 的表逐项核对，先把端口切回明文 1883 测试，Client ID 加随机后缀，确认 Broker 侧服务确实在监听对应端口。排查顺序是“地址对不对、端口通不通、认证过不过”，别一上来就怀疑扩展本身。
4.3 能连上但收不到订阅消息
现象：连接状态正常，发布消息 Broker 侧能看到，但应用收不到订阅主题的消息。原因常见于订阅时机太早（连接未完成就订阅）、主题层级写错（多一个斜杠或少一层）、发布方和订阅方主题不一致。解决：把订阅调用挪到连接成功事件里，主题字符串逐字符核对，先用一个最简单的单层主题做收发测试，通了再换回业务主题。
4.4 两个设备互相踢下线
现象：两台设备用同一套配置，轮流出现“能收一会儿就断”。原因就是 Client ID 重复，Broker 按 Client ID 维持会话，后连的会把先连的顶掉。解决：给每台设备的 Client ID 加唯一后缀，比如设备标识加时间戳。这个坑在课堂演示里特别常见，因为大家习惯直接复制同一份配置。
4.5 退出应用后 Broker 侧残留会话
现象：重新打开应用连接变慢或被拒。原因是退出时没调断开连接，Broker 保留了旧会话。解决：在屏幕关闭或退出逻辑里显式调用断开，必要时在 Broker 侧清理残留会话。我一般把断开连接当成和连接同等重要的块来拼，不省这一步。
5. 装完怎么验证：三步确认 MQTT 链路真的通了
验证不要只看“连接状态变成已连接”就收工，那只能说明 TCP 层通了。我习惯分三步走，每步都有明确的观察点。
第一步，连接与订阅的确认。打开应用触发连接，观察连接成功事件是否被触发，再确认订阅调用执行后没有报错。这一步的观察点是事件顺序：连接成功在前，订阅在后。如果订阅块在连接成功之前执行，说明拼块顺序有问题，回到 3.3 调整。
第二步，用外部客户端做交叉验证。在电脑上用一个独立的 MQTT 客户端连同一个 Broker，向应用订阅的主题发一条测试消息，看应用的消息到达事件是否触发、内容是否一致；再从应用发布一条消息，看外部客户端能否收到。这一步能区分“应用侧问题”和“Broker 侧问题”。交叉验证时注意外部客户端的 Client ID 也要唯一，别和应用撞了。
第三步，做一次断线重连测试。手动断开网络或停掉 Broker 再恢复，观察应用是否能重新连接并恢复订阅。这一步最容易被跳过，但真实使用环境里网络抖动是常态。如果重连后收不到消息，多半是重连逻辑里漏了重新订阅，需要在连接成功事件里统一处理订阅，而不是只在初始化时订阅一次。
验证清单（按顺序打勾）： [ ] 连接成功事件触发，状态为已连接 [ ] 订阅调用在连接成功之后执行 [ ] 外部客户端发消息，应用能收到且内容一致 [ ] 应用发消息，外部客户端能收到 [ ] 断网恢复后能自动重连并恢复订阅 [ ] 退出应用后 Broker 侧无残留会话这份清单我每次搭 MQTT 原型都会走一遍，尤其是最后两项，出问题往往不是扩展的锅，而是拼块逻辑漏了收尾。UrsAI2Paho 扩展包把 Paho 的通信能力带进了 APP Inventor 的拼块世界，装它本身不难，难的是把连接、订阅、收发、断开这四段逻辑拼成闭环。从那以后我每次导入扩展前都先备份项目、每次连 Broker 前都先核对参数表、每次收工前都强制走一遍断线重连验证，这三件事让我少熬了很多夜。希望帮到你。
本文还有配套的精品资源，点击获取
