2、开发机基础环境准备：JDK 11/17安装与配置、Maven 3.8+安装与配置、Git安装与配置、Node.js 16+与npm/yarn安装

好，咱们正式开始动手。这一章我带你搞定开发机的基础环境。

说白了，ThingsBoard 是个 Java 项目，前端又用了 Angular。所以 JDK、Maven、Git、Node.js 这几样东西，一个都不能少。

我个人习惯先把环境捋顺了再干活。不然编译到一半报个错，查半天发现是 JDK 版本不对，那太浪费时间了。

2.1 JDK 11/17 安装与配置

ThingsBoard 官方推荐 JDK 11。不过从 3.5 版本开始，JDK 17 也能跑得很稳。我建议你直接装 JDK 17，省得以后升级还得折腾。

重要提示：ThingsBoard 用到了很多 Java 模块化特性。JDK 8 是绝对不行的，别试。

2.1.1 下载与安装

去 https://adoptium.net/ 下载。选 Temurin 版本，这是社区维护的，没有版权问题。

Linux 用户，我推荐用压缩包解压的方式。为什么？因为用包管理器装，有时候路径会乱掉。

# 解压到 /opt 目录
tar -zxvf jdk-17_linux-x64.tar.gz -C /opt/

# 重命名一下，方便管理
mv /opt/jdk-17.0.9+9 /opt/jdk17

Windows 用户直接双击 exe 安装就行。记得把安装路径记下来，别用默认的带空格的路径。

2.1.2 配置环境变量

嗯，这里要注意。很多新手配环境变量只配了 JAVA_HOME，忘了配 PATH。

# 编辑 ~/.bashrc 或 ~/.zshrc
export JAVA_HOME=/opt/jdk17
export PATH=$JAVA_HOME/bin:$PATH

配完之后，执行 source ~/.bashrc 让它生效。然后验证一下：

java -version
# 输出应该类似：openjdk version "17.0.9" 2023-10-17

我的小技巧：我习惯在 ~/.bashrc 里加一个 alias jdk8='export JAVA_HOME=/opt/jdk8 && export PATH=$JAVA_HOME/bin:$PATH'。这样切换版本就一行命令的事。

2.2 Maven 3.8+ 安装与配置

ThingsBoard 是个多模块项目，Maven 是它的骨架。版本必须 3.8 以上，不然有些插件不兼容。

我曾经在 3.6.3 上编译 ThingsBoard，结果 mvn install 报了一堆 Unsupported class file major version 的错误。查了半天，就是 Maven 版本太老了。

2.2.1 下载与安装

去 https://maven.apache.org/download.cgi 下载 apache-maven-3.9.6-bin.tar.gz。

# 解压
tar -zxvf apache-maven-3.9.6-bin.tar.gz -C /opt/

# 配置环境变量
export MAVEN_HOME=/opt/apache-maven-3.9.6
export PATH=$MAVEN_HOME/bin:$PATH

2.2.2 配置 settings.xml

这个文件是 Maven 的灵魂。我建议你直接修改 $MAVEN_HOME/conf/settings.xml，而不是用户目录下的那个。因为团队协作时，统一配置更方便。

主要改两个地方：

  1. 本地仓库路径：默认在 ~/.m2/repository，我习惯改到 /opt/maven-repo，方便多项目共享。
  2. 镜像源：国内用户一定要配阿里云镜像，不然下载依赖能等到你怀疑人生。
<settings>
  <localRepository>/opt/maven-repo</localRepository>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/central</url>
    </mirror>
  </mirrors>
</settings>

注意：ThingsBoard 依赖的某些包（比如 thingsboard-mqtt-client）在阿里云镜像里可能没有。如果编译报 404，记得切回中央仓库试试。

2.3 Git 安装与配置

Git 不用多说，搞开发的都得装。ThingsBoard 的源码在 GitHub 上，你得用 Git 把它拉下来。

2.3.1 安装

Linux 用户：

sudo apt-get install git   # Ubuntu/Debian
sudo yum install git       # CentOS/RHEL

Windows 用户去 https://git-scm.com/ 下载安装包。安装时记得勾选「Git Bash Here」和「Git GUI Here」。

2.3.2 基础配置

装完之后，先配用户名和邮箱。不然提交代码时会报错。

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

我个人还喜欢配两个别名：

git config --global alias.co checkout
git config --global alias.br branch

这样敲 git co 就能切换分支了，省时间。

2.3.3 拉取 ThingsBoard 源码

找个干净的目录，执行：

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

这个过程大概要几分钟，取决于你的网速。拉完之后，你可以切到最新的稳定版分支：

git checkout release-3.6

我的习惯：我不会直接在主分支上改代码。我会先 git checkout -b my-dev 创建一个自己的开发分支。这样万一改坏了，切回主分支就恢复了。

2.4 Node.js 16+ 与 npm/yarn 安装

ThingsBoard 的前端部分是用 Angular 写的。编译它需要 Node.js 和包管理器。

版本要求：Node.js 必须 16 以上。我建议装 18 LTS，稳定又够新。

2.4.1 安装 Node.js

我推荐用 nvm（Node Version Manager）来装。为什么？因为你可以随时切换版本，不用重新下载。

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载终端
source ~/.bashrc

# 安装 Node.js 18
nvm install 18

# 使用 18 版本
nvm use 18

验证一下：

node -v   # 输出 v18.19.0
npm -v    # 输出 10.2.3

2.4.2 配置 npm 镜像

国内用户，这一步必须做。不然 npm install 能卡死你。

npm config set registry https://registry.npmmirror.com

配完之后，你可以用 npm config get registry 检查一下。

2.4.3 安装 yarn

ThingsBoard 官方用的是 yarn。虽然 npm 也能用，但我建议你装 yarn，因为它的依赖解析更稳定。

npm install -g yarn

装完之后，同样配一下镜像：

yarn config set registry https://registry.npmmirror.com

避坑指南：我曾经在 Windows 上遇到 yarn install 报 EPERM 错误。后来发现是权限问题。解决方案：用管理员身份打开 PowerShell，或者把项目放到非系统盘（比如 D 盘）。

2.5 环境验证清单

所有东西装完之后，我建议你跑一遍这个清单。确保每个工具都能正常工作。

工具 验证命令 预期输出
JDK java -version openjdk version "17.0.9"
Maven mvn -version Apache Maven 3.9.6
Git git --version git version 2.34.1
Node.js node -v v18.19.0
npm npm -v 10.2.3
yarn yarn -v 1.22.21

好，到这步为止，你的开发机基础环境就准备好了。下一章我们开始编译 ThingsBoard 源码。到时候你会发现，环境配得好，编译没烦恼。

总结一下：JDK 17 + Maven 3.9 + Git + Node.js 18 + yarn，这是目前最稳的组合。别问我为什么不用最新版，稳定压倒一切。

← 上一章 📖 返回目录 下一章 →