3. 开发环境搭建与源码编译

ThingsBoard 是一个典型的 Java + Angular 双栈工程：后端基于 Spring Boot 与 Akka，前端基于 Angular 与 TypeScript，构建工具统一使用 Maven（前端通过 frontend-maven-plugin 调用 npm）。因此，能否顺利编译，取决于 JDK、Maven、Node.js 三者的版本是否与目标分支匹配。本节以社区版（CE）为例，走通“环境准备 → 源码获取 → 分支选择 → 前后端编译 → 本地启动 → 问题排查”的完整链路。

一、JDK 与 Maven 环境配置

版本匹配是第一步。ThingsBoard 3.6.x 及之后的版本要求 JDK 17，3.4.x～3.5.x 使用 JDK 11，更早的 3.2.x 及以前使用 JDK 8。选错 JDK 会在编译期直接抛出 Unsupported class file major version 或 Lombok 相关的注解处理异常。Maven 建议使用 3.8.x 或 3.9.x，过低版本无法解析部分插件。

安装完成后必须验证，而不是“装完即认为可用”。在终端执行：

java -version
# 期望输出：openjdk version "17.0.x" ...

mvn -v
# 期望输出：Apache Maven 3.9.x
#          Java version: 17.0.x, vendor: ...

echo $JAVA_HOME
# 期望输出：/usr/lib/jvm/jdk-17（Linux/macOS）
# Windows 下为 %JAVA_HOME%，如 C:\Java\jdk-17

关键判断点有三个：java -version 的主版本号、mvn -v 中显示的 Java version 是否与之一致、JAVA_HOME 是否指向同一 JDK。三者不一致是后续编译失败最常见的根因——例如系统 PATH 里是 JDK 17，但 JAVA_HOME 仍指向旧的 JDK 8，Maven 会按 JAVA_HOME 编译，从而报错。

Maven 还需要配置国内镜像以加速依赖下载。编辑 ~/.m2/settings.xml，在 <mirrors> 中加入阿里云镜像：

<mirror>
  <id>aliyun</id>
  <mirrorOf>central</mirrorOf>
  <url>https://maven.aliyun.com/repository/central</url>
</mirror>

同时建议把本地仓库放在空间充足的磁盘，默认 ~/.m2/repository 在完整构建后可能占用 2～4 GB。

二、源码获取与分支选择

从官方仓库克隆源码，注意使用 --depth 控制体积，并明确检出目标分支：

git clone https://github.com/thingsboard/thingsboard.git
cd thingsboard
git branch -a                 # 查看所有分支
git checkout release-3.6      # 检出稳定发布分支
git log -1 --oneline          # 确认当前提交

分支选择遵循“稳定优先”原则：master 是开发主线，功能最新但可能处于不可编译状态；release-x.y 是发布分支，适合学习与二次开发；release-x.y.z 标签对应具体补丁版本，最稳定。若只是本地跑通，优先选 release-3.6 这类分支，避免踩到主线正在重构的坑。

三、前后端编译流程

ThingsBoard 的 Maven 构建分为两个阶段：先编译 UI 模块（生成静态资源），再编译后端服务。首次构建建议跳过测试以节省时间：

# 仅编译 UI（Angular 打包，耗时较长）
mvn clean install -pl ui -am -DskipTests

# 编译整个项目（含后端各模块）
mvn clean install -DskipTests

# 若只需后端，可跳过 UI
mvn clean install -DskipTests -Dmaven.test.skip=true -pl !ui

编译过程中值得关注的信号：UI 阶段会下载 Node.js 与 npm（由 frontend-maven-plugin 管理），若卡在 Downloading node 说明网络受限；后端阶段若出现 Could not resolve dependencies，多为镜像未生效或依赖坐标写错。构建成功的标志是各模块输出 BUILD SUCCESS，并在 application/target/ 下生成可执行的 thingsboard.deb 或 thingsboard.rpm（取决于打包配置）。

四、本地启动与常见问题排查

编译成功后，最简启动方式是直接运行打包产物：

java -jar application/target/thingsboard.jar

默认使用内存数据库（H2）与内存队列，适合快速验证。启动成功的判断依据有三条：控制台出现 Started ThingsBoardApplication in xx seconds；日志中无 ERROR 级别的数据库或队列异常；浏览器访问 http://localhost:8080 能看到登录页，默认账号 tenant@thingsboard.org / tenant。

若启动失败，按以下顺序排查：

• JDK 版本不符：报 Unsupported class file major version 61 说明用 JDK 8 跑了 JDK 17 编译的字节码，检查 JAVA_HOME 与 PATH 是否一致。
• 依赖下载失败：报 Could not resolve dependencies，先确认 settings.xml 镜像生效，再执行 mvn -U clean install 强制更新。
• 端口占用：报 Port 8080 was already in use，用 lsof -i:8080（Linux/macOS）或 netstat -ano | findstr 8080（Windows）定位进程并释放。
• 数据库连接超时：若切换为 PostgreSQL，需在 thingsboard.yml 中配置 spring.datasource.url、用户名与密码，并确认数据库已建库。
• 前端资源 404：说明 UI 模块未编译或未打包进 jar，重新执行 mvn clean install -pl ui -am。

完成以上步骤后，你得到的是一个可运行、可调试的本地 ThingsBoard 实例。后续无论是修改后端逻辑还是调整前端页面，都可以基于这套环境进行增量编译与热部署验证。