折腾 JDK21 并不是什么新鲜事但我在实际环境里反复踩过几轮坑之后发现真正让人头疼的往往不是 JDK 本身而是“下载渠道怎么选”“环境变量配置完怎么就是不生效”“Linux 新服务器上到底哪种安装方式最省事”“项目里老库能不能跑在 JDK21 上”。这篇攻略是 Day03 的实战记录整理自 KAUKAU 的真实安装过程把 JDK21 下载、JDK21 安装步骤、JDK21 配置环境变量这几个环节尽量讲透Windows、Linux、macOS 三个平台都覆盖到顺便把 aspose-words 这类 Java 库的版本兼容性也说了。如果你正准备在新电脑、新服务器上装 Java 21或者正在纠结到底该用哪个发行版这篇内容应该能帮你省下不少试错时间。1. JDK21 下载之前先搞清楚这三件事1.1 JDK21 到底是什么级别的版本值不值得换JDK21 是 Oracle 在 2023 年 9 月发布的长期支持版本LTS这个“长期支持”意味着官方会提供多年的安全和稳定更新。Java 的版本策略很有意思每 6 个月发布一个非 LTS 版本3 年发布一个 LTS 版本所以 JDK17 之后的下一个 LTS 就是 JDK21。很多团队现在还在 JDK8 或者 JDK11 上听到 21 会下意识觉得跨版本太大但实际上 JDK8 到 21 的迁移路径已经非常成熟绝大多数框架和中间件都已经适配过了。JDK21 最值得关注的新特性就是虚拟线程Virtual Threads。你如果写过 Java 并发应该对线程池、Future、CompletableFuture 这些老一套不陌生虚拟线程的出现让高并发场景可以写出更加直观的线程模型不需要为了性能去硬啃复杂的异步回调。另外 switch 模式匹配、Record 模式、分代 ZGC 这些特性在 21 里也都正式落地了。对于新项目来说直接用 21 完全没有心理负担对于老项目只要有资源做一次验证多数情况下升级收益也比想象中大。1.2 OpenJDK、Oracle JDK、Temurin、Zulu 到底选哪个这里的“JDK21 下载”不是只有一个官网入口而是有好几个发行版可以选。Oracle JDK 是最“正宗”的但它有商用许可协议线上生产环境如果直接频繁使用需要留意条款。个人学习、本地开发基本没问题但很多企业为了规避风险更愿意选择完全开源的 OpenJDK 构建版本。比较常见的有这几个发行版维护方特点Oracle JDKOracle官方原版性能调优最完整商用需要授权OpenJDK社区 各厂商完全开源功能上与 Oracle JDK 几乎一致TemurinAdoptiumEclipse 基金会免费、开源、适合生产环境社区活跃ZuluAzulAzul Systems多平台支持好兼容性测试充分Amazon CorrettoAmazon免费多平台AWS 环境友好我个人如果是在新服务器上装优先选 Temurin 或者 Amazon Corretto因为这两个在 Linux 下有完整的系统包或者 tar.gz 包而且升级渠道干净。如果只是跑一个本地项目Oracle JDK 也无所谓。实际上这几个发行版在 API 层面完全一致只是构建方和许可证不同不需要在“哪个更快”上纠结太久。1.3 下载 JDK21 的不同渠道哪个最不容易踩坑JDK21 下载有三种常见方式官方或 Adoptium 网站手动下载、包管理器自动安装、SDKMAN 这类版本管理工具安装。手动下载适合你要装到离线的服务器或者需要指定某个非常具体的构建版本的情况。包管理器比如 Linux 上的 apt、yummacOS 上的 Homebrew适合系统环境统一管理但不一定能第一时间拿到最新小版本。SDKMAN 是很多 Java 开发者的心头好它天然支持多版本切换装了 17 和 21 可以随时切换不需要手动去改环境变量非常适合本机同时维护多个项目的人。如果你第一次装 JDK21我建议照着下面的内容操作之前先确定自己是“想装一个长期稳定版本”还是“想随便试试”两条路线的安装细节差别其实并不大但思考清楚了后面就不容易乱。2. 安装前必看版本号、架构和包类型的几个细节2.1 jdk-21 和 jdk-21.0.x 有什么区别JDK21 这个称呼是一个大版本名实际上你在下载站点看到的名字可能是jdk-21.0.1、jdk-21.0.2这样的具体小版本。小版本是安全更新和 bug 修复不影响你理解的 Java 版本语义但大版本内部的差异并不影响代码编译和运行。只要你的代码是编译目标为 21那么 21.0.1 和 21.0.4 之间你基本感知不到差别除非你在用某些跟 JVM 内部实现相关的工具。因此你在安装时不需要死盯着“最新小版本”遇到 21.0.2 也完全可以装续期的时候到官方网站或者软件源里再查一下即可。2.2 系统架构的坑x86_64 与 aarch64 别选错这个坑我在 Linux 新服务器上踩过好几次。下载 JDK21 的 tar.gz 包时下载站点一般会同时提供x64和aarch64两种架构。x64 是传统的 Intel/AMD 芯片aarch64 是 ARM 架构。如果你在 ARM 服务器上装了一个 x64 的包最常见的提示就是cannot execute binary file或者Exec format error非常让人崩溃。这个错误其实和 JDK 本身没关系纯粹是包选错了。怎么确认系统架构Linux 上跑uname -m就能看到结果。x86_64 对应x86_64或amd64ARM 对应aarch64或arm64。macOS 上跑uname -mApple Silicon 会显示arm64Intel 芯片显示x86_64。下载之前先跑一条命令确认比装完报错再回来折腾舒服得多。2.3 tar.gz 包、msi/exe 包、pkg 包分别适合什么场景tar.gz 是 Linux 上最原始的压缩包形式解压之后就是一个完整的 JDK 目录把它放到指定位置再配环境变量就行。这种方式的优点是完全可控缺点是升级时要自己替换、自己清理旧版本。Windows 上有.exe和.msi两种安装包双击安装后会写入注册表环境变量有时会自动配置好对于桌面用户最省心。macOS 上的.pkg安装包也一样安装后会有系统级的 Java Virtual Machine 注册直接能被java命令识别。还有一类是 Homebrew 或 apt 安装的版本这种方式会将 JDK 纳入系统包管理卸载和升级都很简单。如果你不排斥用命令安装我其实挺推荐 Linux 新服务器走 apt 或 yum不用下载、不用解压、不用自己写 profile 脚本只是有些源里的版本会稍微滞后一点。2.4 下载文件一定要校验 SHA256 吗除非是从被污染的第三方站点下载否则正规站点下载 JDK21 基本不需要额外校验。但如果你在企业内网或者下载站镜像是第三方维护的我建议花十秒钟做一次 SHA256 校验。Adoptium、Oracle 官网都会给出对应的校验值Linux 上用sha256sum 文件名macOS 上用shasum -a 256 文件名Windows 上用 PowerShell 的Get-FileHash。校验值一致说明文件没被篡改这属于安全习惯不是多余动作。3. Windows 平台安装 JDK21 的完整流程3.1 Windows 下用安装包安装最省心的方案Windows 用户最直观的路径就是去 Adoptium 或 Oracle 官网下载.exe或.msi文件然后双击安装。我建议用.msi格式因为 MSI 安装包自带了系统级的配置能力能写注册表后续 Windows 系统识别已安装的 Java 会更规范。安装时有两个细节值得注意第一安装路径尽量不要选带空格和中文的目录虽然理论上 JDK 支持但后面配环境变量、写脚本时容易多一层转义问题。我常用的目录是C:\Program Files\Java\jdk-21这个路径本身是有空格的配置环境变量时用引号包起来就没问题。第二安装过程中会有一步“设置 JAVA_HOME”的选项如果你用的是 Oracle 安装包或者 Adoptium MSI一定要确认它帮你写了正确的路径有些安装包默认只往 PATH 里追加 java 命令没有设置 JAVA_HOME。3.2 配置 JAVA_HOME 和 PATH到底要不要配 CLASSPATH现在很多教程还在教人配置 CLASSPATH实际上 JDK5 之后就已经很少需要了JDK21 更是不建议手动设置 CLASSPATH反而容易干扰构建工具。你在 Windows 上需要做的只有两件事新建一个JAVA_HOME系统变量指向 JDK 根目录再把%JAVA_HOME%\bin追加到 Path 变量。操作方法很简单右键“此电脑” → 属性 → 高级系统设置 → 环境变量。在系统变量区域点击“新建”变量名填JAVA_HOME变量值填你的安装路径比如C:\Program Files\Java\jdk-21。然后在 Path 变量里点击“编辑”新建一行%JAVA_HOME%\bin。这里有个细节新建的 Java bin 路径最好排在 Path 列表的前面因为 Windows 会从左往右找第一个 java.exe如果你机器上还装了其他版本的 JDK旧的路径排在前面你就算把 JAVA_HOME 改了java -version显示的也还是旧版本。3.3 环境变量配置之后怎么验证生效配完环境变量需要重新开一个命令行窗口因为已经打开的窗口不会自动加载新的环境变量。在 CMD 或者 PowerShell 里分别执行java -version和javac -version看到 21 开头的版本信息就说明安装成功。如果java -version能执行但显示的不是 21大概率就是 Path 里还有其他 JDK 排在前面。这时候执行where java系统会列出所有找到的 java.exe 路径看你预期的那一个是不是排在第一位。如果java命令找不到而javac能执行多半是 PATH 里只有%JAVA_HOME%\bin的一部分或者 JAVA_HOME 路径写错了检查变量值和路径是否真实存在。3.4 Windows 下容易忽略的小问题安装完 JDK21 之后如果你用 IntelliJ IDEA 或 Eclipse记得在 IDE 里把 JDK 切换到 21。IDE 里的 SDK 设置是独立的不会自动跟随系统环境变量。如果你用 Maven还要确认JAVA_HOME被 IDE 或者 Maven 正确读取因为 Maven 启动脚本直接依赖 JAVA_HOME而不是 PATH。另外如果你的系统是 Windows Server 且装了多个版本的 Java建议把旧版本卸载干净或者明确用JAVA_HOME指向 21。实战中我见过因为 path 里残留了某个工具自带的 JDK8导致项目在命令行编译正常、在 IDE 里却死活编译不过的情况最后发现是 IDE 的终端用了系统 PATH而 PATH 的前面被旧 JDK 占了。4. Linux 新服务器如何设置 JDK21 环境变量4.1 新服务器第一步系统检查和架构确认拿到一台全新的 Linux 服务器第一件事不是急着下载 JDK21而是先检查系统里有没有已经存在的 Java。执行java -version和which java如果命令存在但版本不是你要的先确认它的来源很多系统镜像会自带 OpenJDK。如果确认是多余版本可以直接卸载或者暂时不管用新配置的环境变量把 PATH 顺序压过去。接着跑uname -m确认架构再跑cat /etc/os-release看发行版类型。判断了是 Ubuntu/Debian 还是 CentOS/Rocky 之后安装方式会完全不同前者用 apt 系列后者用 yum/dnf 系列。4.2 用包管理器安装 JDK21一条命令搞定Ubuntu 22.04 或者 24.04 上只需要执行sudo apt update sudo apt install openjdk-21-jdk如果是 CentOS 或者 Rocky Linux用sudo yum install java-21-openjdk-devel包管理器安装完成之后Java 会被放在系统管理的路径下JAVA_HOME可以使用系统提供的工具查出来。比如 CentOS 上执行alternatives --list能看到java和javac对应的候选路径Debian/Ubuntu 上可以执行update-alternatives --list java。这种方式最大的好处是省去手动配JAVA_HOME的过程。不过包管理器装的 JDK 不一定会自动设置 JAVA_HOME 环境变量很多系统只是把 java 软链到了/usr/bin/java。如果你在跑 Tomcat、Maven 这类依赖 JAVA_HOME 的应用还是要自己补一个 JAVE_HOME 配置。常见的做法是查一下路径比如sudo update-alternatives --config java查看当前 java 的路径顺着路径往上找到 JDK 的根目录然后写入环境变量。4.3 手动解压 tar.gz 安装可控性最强的方案很多企业服务器不能随便用公共软件源手动安装反而是最稳妥的方式。先到 Adoptium 或 Oracle 官方站点下载对应的 tar.gz 包然后执行sudo mkdir -p /opt/jdk sudo tar -xzvf jdk-21_linux-x64_bin.tar.gz -C /opt/jdk解压后目录一般是/opt/jdk/jdk-21.0.x。接下来创建/etc/profile.d/jdk21.sh文件这是 Linux 环境变量推荐的做法因为/etc/profile.d下的脚本会在用户登录时自动被加载比手动修改/etc/profile更清晰也方便后续清理。内容如下sudo vim /etc/profile.d/jdk21.sh export JAVA_HOME/opt/jdk/jdk-21.0.x export PATH$JAVA_HOME/bin:$PATH保存后执行source /etc/profile.d/jdk21.sh或者退出 SSH 重新登录。验证时注意执行which java确保/usr/bin/java已经被/opt/jdk/jdk-21.0.x/bin/java覆盖。4.4 为什么推荐 profile.d 而不是直接改 /etc/profile直接修改/etc/profile虽然也能生效但不利于维护。假如你以后装了一个 JDK22想把 21 换掉你只需要修改jdk21.sh里的路径或者删除这个文件不影响系统级的 profile 内容。对于新服务器来说这个习惯从第一天就养成会省很多事。还有一个细节是如果你当前登录的用户已经存在source只能让当前 shell 生效但新开的 SSH 会话会重新读取/etc/profile.d下的脚本所以新会话里肯定能生效。如果在脚本里漏了export只有当前会话里能访问新会话里环境变量就丢了这也是新手经常遇到的问题。4.5 Linux 上安装完后的常规验证验证命令顺序很重要java -version javac -version echo $JAVA_HOME如果java -version正常但echo $JAVA_HOME为空说明配置里漏了 export 或者配置文件没被加载。如果javac找不到说明安装的是 JRE 而不是 JDK开发生态里肯定需要 JDK这个很容易被不知名的包管理器误导。还有一个小坑某些 Linux 系统为了方便自带了 JRE 路径但javac并不存在这时候要确认装的包是-devel版本而不是纯 runtime 版本。5. macOS 中安装 JDK21 的几种实用方法5.1 方法一Homebrew 安装最省心但需要手动链接macOS 上如果已经安装了 HomebrewJDK21 的安装非常简单brew install openjdk21不过这个命令安装完并不会自动出现在系统默认的java命令路径里Homebrew 在安装完成后的输出里会有提示让你把 JDK 链接到系统 Java 目录。跟着提示执行sudo ln -sfn /opt/homebrew/opt/openjdk21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk这样做的原理是 macOS 会通过/Library/Java/JavaVirtualMachines目录来发现系统中安装的 JDK链接创建之后/usr/libexec/java_home也能正确识别。5.2 方法二直接下载 pkg 安装包如果你不想用命令安装也可以直接访问下载站点获取 macOS 版本的.pkg文件双击安装。装完之后 JDK 会自动注册到/Library/Java/JavaVirtualMachines/jdk-21.jdk系统会默认使用它。这种方式对大多数桌面用户来说是最无感的不用动环境变量java -version直接就能生效。不过有一点注意如果你的 Mac 是 Apple Silicon 芯片下载包要选macOS aarch64版本不是x64。如果你选错了 x64系统会通过 Rosetta 2 执行性能会有损失而且部分原生 SDK 工具链会出现奇怪问题。5.3 方法三使用 SDKMAN 做多版本管理macOS 上如果经常要在 JDK17、JDK21 之间切换我强烈推荐 SDKMAN。安装 SDKMAN 只需要一行命令curl -s https://get.sdkman.io | bash然后sdk install java 21.0.4-tem sdk use java 21.0.4-temSDKMAN 的好处是它会把 JDK 安装到用户目录下不污染系统路径切换版本只需要一条sdk use命令不会出现环境变量改来改去的痛苦。5.4 macOS 的 java_home 命令又是什么macOS 上有一个很特别的命令/usr/libexec/java_home它会列出系统识别到的所有 JDK并输出对应的 JAVA_HOME 路径。装了多个版本之后很多人会直接把这个路径写进~/.zshrcexport JAVA_HOME$(/usr/libexec/java_home -v 21)这样写的好处是 JDK 位置由系统统一管理即使路径变了也能自动解析到正确位置。我自己的习惯是在~/.zshrc里保留这一行然后用 alias 或者 SDKMAN 来做版本切换两者不冲突。6. 项目里的兼容性排查以 aspose-words 为例聊聊 JDK216.1 为什么 Java 库会和 JDK 版本不兼容JDK 版本升级之后最典型的问题就是字节码版本。每个 JDK 编译出来的 class 文件都有特定的 major versionJDK8 编译的是 52JDK11 是 55JDK17 是 61JDK21 是 65。如果你的项目里引用了一个很老的 jar 包它在编译时用了旧 JDK理论上反而可以跑在更高版本上因为 JVM 是向后兼容的。真正的问题通常出现在两类情况一是老库用到了已删除或过时的 API二是库的字节码版本高于当前 JVM 能识别的版本。JDK21 环境下相对麻烦的是那些很久不更新的老库。它们可能还在用sun.misc包里的东西或者依赖被移除的 SecurityManager这些类在 JDK17 之后就已经默认不可用了。遇到这种情况最好先看看库的官网有没有更新版本如果没有就得考虑替换方案或者降级 JDK。6.2 具体到 Aspose.Words for Java哪个版本兼容 JDK21Aspose.Words 是一个很常用的文档处理库很多人用它来做 Word、PDF、HTML 之间的转换。按照官方发布周期的规律Aspose.Words 的每个新版本都会尽量保持对主流 Java 版本的兼容。就 JDK21 来说建议用 24.12 或之后的版本这类新版本对 JDK21 的支持比较完整官方文档里也明确列出了测试过的 JDK 版本。如果你正在用的是 24.12 之前的版本并不一定跑不起来只是遇到奇怪问题时可能没人给你背锅。在 Maven 中引入一个较新的版本可以参考下面的配置dependency groupIdcom.aspose/groupId artifactIdaspose-words/artifactId version24.12/version /dependencyGradle 则是implementation com.aspose:aspose-words:24.12需要注意 Aspose.Words 的 Maven 仓库并不是 Maven Central它有自己的仓库地址需要额外配置。你在项目里引入时如果一直拉不下来大概率就是仓库地址没有加上。6.3 其他生态工具的兼容性排查思路除了 aspose-words实际项目里经常还有 POI、itext、Lombok、Spring Boot 这些库。Spring Boot 官方文档会明确说明支持的 JDK 版本比如 Spring Boot 3.2 以后对 JDK21 支持良好。POI 5.2 以上也支持 JDK21。Lombok 需要 1.18.30 以上才能在 JDK21 下正常编译。检查思路其实很简单先去项目官网看最低要求再看是否是 LTS 版本的官方测试范围。如果你拿到一个老 jar不确定它能不能在 JDK21 下跑可以用javap -verbose xxx.class | grep major看看这个类的字节码版本。如果 major version 是 52 或更低那它理论上可以在 JDK21 上跑因为旧的字节码能被新的 JVM 加载。如果 major version 是 64 甚至更高说明这个库本身就是用更高版本 JDK 编译的当前 JVM 自然加载不了这时候必须升级 JDK 版本而不是库。7. 常见问题与排查技巧实录7.1 Windows 上配完环境变量为什么死活不生效这个问题排第一。常见原因有三个第一配置完没有重新打开终端Windows 的终端窗口在启动时读取环境变量已经打开的窗口不会更新。第二变量值写成了C:\Program Files\Java\jdk-21\bin而不是C:\Program Files\Java\jdk-21导致 JAVA_HOME 本身就不对。第三Path 里同时存在多个 java 路径系统找到了旧版本。排查方法在 CMD 里执行echo %JAVA_HOME%看输出如果为空或者不是你配的路径说明系统变量没有写入成功。执行where java看系统实际找到的 java 路径如果是旧版本回到环境变量编辑界面把%JAVA_HOME%\bin上移到最前面。7.2 Linux 新服务器上 java: command not found 怎么办如果你已经按照 4.3 的方式配置了 profile.d 文件但还是提示 command not found多半是当前会话没有重新 source。执行source /etc/profile.d/jdk21.sh然后再跑java -version。如果 source 之后还是找不到检查路径是否真实存在比如/opt/jdk/jdk-21.0.x这个目录名字是不是写错了。还有一种可能是当前用户使用的是别的 shell比如 zsh它不一定读取/etc/profile这时候需要在用户的~/.zshrc或~/.zprofile里加上同样的 export。7.3 macOS 上提示无法打开或 command not found: javamacOS 上如果是 pkg 安装应该不会有问题。如果是 Homebrew 装的但没执行链接系统是找不到 java 的。先去跑/usr/libexec/java_home -V看看系统是否识别到 JDK。如果识别到了说明只是 shell 环境没有配置在~/.zshrc里加一行export JAVA_HOME$(/usr/libexec/java_home -v 21) export PATH$JAVA_HOME/bin:$PATH如果/usr/libexec/java_home -V输出列表里根本没有 JDK21说明 JDK 没有被注册到系统检查安装步骤里的 ln -sfn 那一步是否执行成功。macOS 上还有一种情况是下载安装包时因为安全策略被阻止打开到“系统设置 → 隐私与安全性”里允许来自被阻止的开发者即可。7.4 多版本 JDK 怎么切换最顺手开发环境里同时存在 JDK8、17、21 是很正常的。Windows 上切换版本主要靠修改 JAVA_HOME 指向和调整 PATH 顺序但每次手动改环境变量太痛苦。Linux 上用update-alternatives --config java可以快速切系统默认 java但切换 javac 需要再做一次。macOS 和 Linux 上最顺手的还是 SDKMAN它能做到在多个 shell 会话之间独立切换版本而且是用户级的不会影响系统其他用户。如果你不想引入额外工具也可以写一个简单的切换脚本作用就是修改一个 ~/.java_home 文件里的路径然后导出一个 alias 出来。但论省心程度我还是更推荐 SDKMAN。7.5 实操过程中最值得保留的三个习惯第一安装完成后一定把java -version和javac -version都跑一遍只验证 java 不验证 javac遇到 Maven 项目照样可能编译失败。第二配置环境变量时所有路径都写绝对路径不要用~这种省略写法因为在某些脚本里波浪号不会自动展开。第三装完新版本 JDK 之后顺手在项目根目录跑一次mvn clean compile或者gradle build尽早暴露兼容性问题而不是等代码写了一大半再来排查。从我个人的经验来看JDK21 的安装过程本身并不难难点在于每次遇到新环境都要重新摸索一遍细节。把上面这些步骤整理成自己的安装清单之后从检查系统架构、下载压缩包、配置环境变量到验证编译基本上十分钟内就能走完全流程。最后再分享一个小技巧无论是 Windows 还是 Linux安装完 JDK 之后我都习惯顺手写一个java_env_test脚本内容只有三行分别输出 JAVA_HOME、java -version、javac -version。以后每次在新环境里部署 Java 项目跑一下这个脚本就能立刻确认环境是否就绪不用再去记忆那些繁琐的验证命令。这个习惯帮我在不少服务器上都快速定位过问题算是 JDK 安装这件事里最值得保留的投资。