2、开发环境搭建：JDK配置、Maven配置、IDE设置、源码编译与本地运行

说实话，搞 ThingsBoard 插件开发，第一步不是写代码，而是把环境搭稳了。我见过太多新手一上来就 git clone 然后 mvn clean install，结果跑了一下午报一堆红错，心态直接崩了。嗯，咱们今天就把这事捋清楚。

2.1 JDK 配置：版本选对，少走弯路

ThingsBoard 是基于 Java 11 构建的。别问能不能用 Java 8 或 Java 17，我试过，不行。官方明确要求 JDK 11，而且最好是 OpenJDK 或 AdoptOpenJDK。

我个人习惯用 Adoptium（原 AdoptOpenJDK）的 JDK 11。下载后配置环境变量：

# Linux / macOS 下配置 ~/.bashrc 或 ~/.zshrc
export JAVA_HOME=/usr/local/jdk-11.0.18
export PATH=$JAVA_HOME/bin:$PATH

# Windows 下在系统变量里添加
JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-11.0.18
PATH=%JAVA_HOME%\bin;%PATH%

配置完记得验证一下：

java -version
# 输出应该类似：openjdk version "11.0.18" 2023-01-17

我在项目中遇到过一个问题：明明装了 JDK 11，但 mvn 编译时总报「不支持的 class version」。后来发现是系统 PATH 里还残留着 JDK 8 的路径。你想想看，两个 JDK 同时存在，优先级高的那个先被找到，就出事了。所以建议把其他 JDK 的路径先清掉。

2.2 Maven 配置：镜像源与内存调优

ThingsBoard 的代码量不小，依赖也很多。我第一次编译时没配国内镜像，等了快两个小时还没下载完。后来配了阿里云镜像，十分钟搞定。

修改 ~/.m2/settings.xml：

<settings>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

另外，Maven 默认内存只有 512MB，编译 ThingsBoard 这种大型项目会直接 OOM。我建议至少给 2GB：

# 在 MAVEN_OPTS 环境变量中设置
export MAVEN_OPTS="-Xmx2048m -XX:MaxMetaspaceSize=512m"

2.3 IDE 设置：IntelliJ IDEA 是首选

说实话，Eclipse 也能用，但我强烈建议用 IntelliJ IDEA Ultimate 版。为什么？因为 ThingsBoard 的代码结构比较复杂，IDEA 的代码导航、重构、调试体验比 Eclipse 好太多。

安装完 IDEA 后，需要安装几个插件：

• Lombok：ThingsBoard 大量使用 Lombok 注解，不装这个插件代码全是红叉
• CheckStyle-IDEA：保持代码风格统一，我习惯在提交前跑一遍检查
• GitToolBox：方便查看 git 提交记录和分支状态

导入项目时，选择「File → New → Project from Existing Sources」，然后选中 ThingsBoard 根目录下的 pom.xml。IDEA 会自动识别这是一个 Maven 项目，开始下载依赖。这个过程大概需要 5-10 分钟，取决于你的网速。

2.4 源码编译：从零到构建成功

环境配好了，咱们开始编译。先克隆代码：

git clone https://github.com/thingsboard/thingsboard.git
cd thingsboard

然后执行编译命令。这里有个坑：ThingsBoard 的构建分两步，先编译核心模块，再编译扩展模块。直接跑 mvn clean install 会报错，因为有些子模块依赖还没准备好。

正确的做法是：

# 第一步：编译核心模块
mvn clean install -pl common,dao,rule-engine -am -DskipTests

# 第二步：编译所有模块
mvn clean install -DskipTests

为什么要先编译核心模块？因为 ThingsBoard 的插件机制依赖于 rule-engine-api 和 common 模块。我在项目中遇到过一个问题：直接全量编译，结果 rule-engine 模块报错说找不到某个类。后来发现是编译顺序的问题，核心模块必须先构建。

编译成功后，你会看到类似这样的输出：

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  08:12 min
[INFO] Finished at: 2024-01-15T14:30:00+08:00

第一次编译大概需要 8-15 分钟，后续增量编译会快很多，一般 1-2 分钟就能完成。

2.5 本地运行：启动 ThingsBoard 服务

编译完成后，咱们启动服务。ThingsBoard 支持两种运行模式：嵌入式数据库（H2）和外部数据库（PostgreSQL）。开发阶段我建议用 H2，省事。

启动命令：

# 使用 H2 数据库（默认）
java -jar application/target/thingsboard-*.jar

# 或者指定使用 PostgreSQL
java -jar application/target/thingsboard-*.jar \
  --spring.profiles.active=postgres \
  --spring.datasource.url=jdbc:postgresql://localhost:5432/thingsboard \
  --spring.datasource.username=postgres \
  --spring.datasource.password=postgres

启动后，打开浏览器访问 http://localhost:8080，默认管理员账号是 sysadmin@thingsboard.org，密码 sysadmin。

启动过程中可能会遇到端口被占用的问题。我习惯在启动前先检查一下：

# Linux / macOS
lsof -i :8080

# Windows
netstat -ano | findstr :8080

如果 8080 端口被占用了，可以换个端口启动：

java -jar application/target/thingsboard-*.jar --server.port=9090

2.6 验证环境：跑一个简单的测试

环境搭好了，咱们验证一下。写一个最简单的插件测试类，确保开发环境能正常工作：

package org.thingsboard.rule.engine.test;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class EnvironmentTest {

    @Test
    public void testContextLoads() {
        System.out.println("✅ 环境搭建成功！ThingsBoard 上下文加载正常。");
    }
}

在 IDEA 里右键运行这个测试类，如果看到绿色勾勾，说明你的 JDK、Maven、IDE 全部配置正确。如果报错，别慌，先检查一下：

• JDK 版本是不是 11？
• Maven 镜像配了没？
• Lombok 插件装了没？

我曾经在帮同事排查环境问题时，发现他装了 JDK 11 但 IDEA 里 Project SDK 还是选的 JDK 8。这种低级错误最容易忽略，但排查起来也最简单。

2.7 避坑指南：我踩过的那些坑

最后，分享几个我实际踩过的坑，希望能帮你省点时间：

问题	原因	解决方案
编译时提示「找不到符号」	Lombok 插件未安装或版本不匹配	安装 Lombok 插件，并确保版本 >= 1.18.20
启动时端口被占用	其他服务占用了 8080 端口	使用 --server.port 参数指定其他端口
数据库连接失败	PostgreSQL 未启动或配置错误	先用 H2 模式开发，生产环境再切 PostgreSQL
编译速度极慢	Maven 内存不足或未配国内镜像	设置 MAVEN_OPTS 并配置阿里云镜像

嗯，环境搭建这块就这些了。说白了，只要 JDK 版本对、Maven 镜像配好、IDEA 插件装全，剩下的就是等编译完成。下一章咱们开始真正写插件代码，到时候你会感谢今天把环境搭得这么稳的自己。