ThingsBoard 移动应用详细讲解

正文与配图整理自《ThingsBoard 移动应用详细讲解》原稿，面向官方 Flutter App（flutter_thingsboard_app）的本地编译与常见问题。

1、安装 Android Studio

打开 Android Studio 下载页，下载安装包后按默认配置安装即可。

2、下载 Flutter SDK

先看 flutter_thingsboard_app 工程里 pubspec.yaml 对 Flutter / Dart 的版本约束，再到 Flutter Archive 下载对应 SDK，并把 bin 加入 PATH。

3、下载 flutter_thingsboard_app

ThingsBoard 服务端版本与 Mobile App 分支要对齐，矩阵见官方文档：Mobile getting started。

例如本机 ThingsBoard 为 3.8.1 时，可拉取 App 1.4.0：

git clone -b release/1.4.0 https://github.com/thingsboard/flutter_thingsboard_app.git

4、用 Android Studio 打开工程

在 Settings → Plugins 安装 Flutter、Dart，并把 Flutter SDK 路径指到本机目录；再配置好模拟器。

若 flutter pub get 报 Dart SDK 过低，例如：

The current Dart SDK version is 2.18.0.
Because thingsboard_app requires SDK version >=3.2.0 <4.0.0, version solving failed.

说明当前 Flutter 太旧，需要按 pubspec.yaml 升级 Flutter（从而带上匹配的 Dart）。

5、Gradle 与 JDK 版本不匹配

常见失败日志：

Unsupported class file major version 65
Gradle version is incompatible with the Java version that Flutter is using for Gradle

本质是：工程 Gradle 版本 与 Flutter / Android Studio 实际在用的 JDK 不一致。例如 ThingsBoard 3.6.x 对应的较旧 Flutter App，往往需要固定到 JDK 11，而不能直接用 JDK 21。

对照 Flutter ↔ Dart 归档 与工程 pubspec.yaml：

6、关键：在 gradle.properties 指定 JDK

在 android/gradle.properties 里显式指定本机 JDK（路径按实际修改）：

org.gradle.java.home=D:\\path\\to\\jdk-11.0.12

App 里配置 ThingsBoard 地址时不要用 localhost，模拟器 / 真机访问不到宿主机环回地址，应使用局域网 IP 或可解析域名：

开启代理后编译运行，进入登录页：

7、登录后提示 version unknown

登录接口可以成功，但随后调用 /api/system/info 时返回：

{"version":"unknown","type":"CE"}

服务端里该接口由 SystemInfoController 提供，依赖注入 BuildProperties 读取构建版本；部分打包 / Spring Boot 环境下 BuildProperties 无法注入，会落入 else 分支写成 unknown：

临时处理：把源码中类似

infoObject.put("version", "unknown");

改成真实版本（例如 "3.5.1"，与当前 ThingsBoard 一致），重启服务端后再用 App 登录。
（生产环境更推荐修好构建信息注入，而不是长期硬编码。）

8、Flutter 工程国际化（中文）

8.1 补充中文词条

在 lib/l10n 下覆盖 / 补全 intl_zh.arb、intl_zh_CN.arb（原稿含完整中文词条，可按需合并到工程）。

8.2 调整 l10n.yaml

示例：

arb-dir: lib/l10n
template-arb-file: intl_zh.arb

（或按工程现有模板 intl_en.arb 配置，保持生成链路一致即可。）

8.3 修改 main.dart

启用生成的本地化委托，并引入：

import 'package:flutter_gen/gen_l10n/messages.dart';

8.4 新增键与页面使用

• 在 intl_zh.arb / intl_zh_CN.arb 增加键，例如 "device": "设备"
• 在 intl_en.arb 同步增加英文键
• 页面通过 S.of(context).xxx（或工程生成的同类 API）读取

然后执行 flutter clean 再运行：

9、release/1.6.0 注意点

9.1 版本关系

1.6.0 对 Flutter / Dart / JDK 要求更高，先对照官方矩阵与 Flutter Archive：

9.2 修改 pubspec 依赖 URL

plugin_wifi_connect 若写成 SSH 地址，本机无 GitHub SSH 密钥时会拉取失败：

plugin_wifi_connect:
  git:
    url: git@github.com:ybeshkarov/plugin_wifi_connect.git

改为 HTTPS：

plugin_wifi_connect:
  git:
    url: https://github.com/ybeshkarov/plugin_wifi_connect.git

9.3 Android Studio 指向对应 Flutter

9.4 使用 JDK 17 并同步 gradle.properties

1.6.0 线路通常需要 JDK 17，在 Android Studio 与 org.gradle.java.home 中保持一致：

10、小结

落地官方 Mobile App 时，优先对齐这条链：

ThingsBoard 版本 ↔ App release 分支 ↔ Flutter / Dart ↔ Gradle / JDK

再处理：服务地址（禁用 localhost）、/api/system/info 的 version、l10n 国际化，以及 1.6.0 上的 git 依赖与 JDK 17。