GraalVM JDK 17 x64安装与native-image避坑

简介：GraalVM JDK 17 Windows x64 二进制包，面向需要在 Windows 64 位环境体验 GraalVM 与 JDK 17 的 Java 开发者、架构师及多语言运行时研究者，可用于搭建高性能 JVM、Native Image 和多语言互操作实验环境。压缩包共 586 个文件，约 305.58MB，以 dll、lib、exe 等运行时与工具组件，jmod、jar 等模块和类库，以及配置、脚本、说明文档为主，目录结构接近完整发行版，便于直接解压部署和按模块查阅。已有 506 人学习下载。内容覆盖 JDK 17 的密封类、记录类、开关表达式、模式匹配与文本块等特性，并保留 Native Image、Truffle 多语言支持和组件管理工具，适合验证本机编译、性能对比、多语言运行及环境配置排查。

1. 解压完 java 就没了：GraalVM JDK 17 Windows x64 卡在哪一步

GraalVM JDK 17 Windows x64 的发行包，文件名大多长成 graalvm-jdk-17-windows-x64-bin.zip 这样，下载下来一两百兆，解压不到一分钟，然后很多人在 cmd 里敲java -version，回车，屏幕上回一句"不是内部或外部命令"。这不是包坏了，也不是下载残缺，而是这类发行版天生没有安装程序——java、javac、native-image 全躺在一个目录里，能不能被系统认出来，完全取决于 JAVA_HOME 指到了哪一层、PATH 里有没有一个更早的 JDK 抢在前面。我见过最典型的现场是：机器上还留着一个当年的 JDK 8，PATH 顺序没动过，javac编译一切正常，等到真要跑 native-image 才炸，报找不到 cl.exe，回头一查，是变量指错和编译链没装两个问题叠在一起。这套环境适合谁？适合要在 Java 在 Windows 上做 AOT 编译、把 Spring 服务打成单个 exe 的人；如果你只是写写普通 Java 业务代码，装完会发现和 OpenJDK 没什么两样。

2. 装前对表：GraalVM JDK 17 的版本取舍与三个硬条件

动手之前先把环境对一遍。这一步省掉，后面每一章都会变成救火。我一般会在一台干净机器上先确认三件事：系统是不是 x64、磁盘还剩多少、解压目标路径长什么样。这三件事任意一件不满足，装完都能跑java -version，但一进 native-image 就各种奇怪报错。

2.1 三个硬条件：架构、系统版本和一块不被同步的磁盘

架构是第一个门槛。发行包名里的 x64 不是装饰，它对应的是 64 位 Windows 可执行文件。在 ARM64 的 Windows 机器上，模拟层能把java跑起来，让你误以为装成功了，但 native-image 走到链接阶段必挂，因为它要调用本机的 64 位编译器和链接器。判断方法很简单，开一个 cmd：

:: 看 PROCESSOR_ARCHITECTURE，AMD64 才是真正的 x64 echo %PROCESSOR_ARCHITECTURE%

输出AMD64说明是 x64；输出ARM64就别在这台机器上折腾 AOT 了，换机器比修环境省时间。

系统版本和磁盘是第二个门槛。Windows 10 1809 及以上、Windows 11 都能跑，更老的版本可能在解压长路径文件时出错。磁盘要分两档看：只跑 JVM 应用，解压后占三四百兆，留 1GB 足够；要跑 native-image，得额外装几个 G 的编译工具，再加上编译过程中的临时文件，我一般要求目标盘剩 12GB 以上，不然编译到链接阶段报磁盘不足，前面十几分钟全白等。

路径这条吃过亏。早些年我把 JDK 解压到用户目录下的一个中文文件夹，平时写代码一点事没有，直到跑 native-image，编译器在临时目录里生成的中间文件路径被截断，报了一串看不懂的 NoSuchFileException。后来统一改成D:\dev\这种短路径，再没复现过。同步盘同理，解压目录一旦被客户端实时同步，编译时文件句柄被占住，构建会毫无征兆地停在半路。

2.2 17 还是 21：什么时候该停在 17

17 和 21 都是长期支持版本，选哪个不是技术洁癖问题，是生态问题。如果你的项目基线本来就是 17，或者依赖的框架、构建插件、字节码增强工具只在 17 上验证过，那就老老实实停在 17，别为了新语法把整条链子拖下水。GraalVM JDK 17 对应的 native-image 对 17 的语言特性支持已经完整，records、sealed、switch 模式匹配都能编，缺的只是 21 才有的虚拟线程那套东西。

什么情况下我会建议直接上 21？新项目、无历史包袱、并且明确要用虚拟线程扛高并发 IO。这时候装 17 反而是给自己埋雷，因为后面要升级 JDK 大版本，native-image 的反射配置、框架版本、编译工具链都得跟着重来一遍。

两个版本可以共存，这不算什么高级技巧，就是环境变量的基本功：装两个目录，比如D:\dev\graalvm-jdk-17和D:\dev\graalvm-jdk-21，用的时候改 JAVA_HOME，开新窗口就生效。不要试图靠改 PATH 里 bin 目录的先后顺序来切版本，那是最容易切错的方式，where java出来一堆结果，你自己都记不清哪个在前。

2.3 只跑应用还是要 AOT：决定要不要装那几个 G 的编译工具

GraalVM JDK 17 相比普通 OpenJDK 17，多出来两样东西：一套用 Java 写的 JIT 编译器，和 native-image 这个能把字节码提前编译成原生可执行文件的工具。第一样东西你基本感知不到，第二样才是装它的理由。

所以装之前先问自己一句：我到底要不要 AOT？如果答案是不需要，那这套环境的安装到第 3 章就结束了，配好 JAVA_HOME 和 PATH，java -version能看到 GraalVM 字样就算完事，不必去碰第 4 章的编译链，也不用往机器上塞几个 G 的 C++ 构建工具。如果答案是需要，那就得提前规划：native-image 在 Windows 上不是纯 Java 的活，它最后要落成一个 PE 格式的 exe，链接阶段必须借系统上的编译器和 SDK，这部分放在第 4 章展开。

3. 解压后的环境变量：JAVA_HOME 指错一层就全盘皆输

这一章是整篇里最容易翻车的地方，也是最不需要技术含量、却最多人栽跟头的地方。核心只有一句话：JAVA_HOME 要指向解压出来的那一层根目录，PATH 里加的是这个根目录下的 bin，而不是根目录本身，也不是 bin 的上一层。

3.1 解压位置的选择与目录结构确认

先说解压。发行包是个标准 zip，用系统自带的解压或者第三方工具都行，但有一点要留意：有些 zip 解压出来的文件会带上"来自网络"的标记，后续调用 exe 时可能被系统拦一下。我习惯解压完顺手清一遍标记：

# 解压到短路径，避免空格、括号和中文 Expand-Archive -Path "$env:USERPROFILE\Downloads\graalvm-jdk-17-windows-x64-bin.zip" ` -DestinationPath "D:\dev\graalvm" -Force # 清掉从网络继承的标记，避免后续调用被拦 Get-ChildItem "D:\dev\graalvm" -Recurse | Unblock-File

Expand-Archive的-DestinationPath只决定外层目录，zip 内部通常还自带一层版本目录，这是很多人第一次配错的原因。解压完别急着配变量，先看一眼目录结构：

# 第一层：应该只有一个 graalvm-jdk-17 开头的目录 Get-ChildItem "D:\dev\graalvm" | Select-Object Name # 第二层：这才是真正的 JAVA_HOME，里面应该有 bin、conf、lib、jmods、release Get-ChildItem "D:\dev\graalvm\graalvm-jdk-17*" | Select-Object Name

期望的第二层输出是bin、conf、include、jmods、legal、lib、release这几项。看到release文件就说明找对地方了，顺手读一下确认版本：

# JAVA_VERSION 是 JDK 版本，IMPLEMENTOR 能看出是不是 GraalVM 发行版 Get-Content "D:\dev\graalvm\graalvm-jdk-17\release" | Select-String "JAVA_VERSION|IMPLEMENTOR"

如果第一层就已经是 bin、lib，说明这个包没有外层版本目录，那 JAVA_HOME 直接指第一层。两种情况都正常，区别只在于包是怎么打的，判断标准始终是"哪一层下面有 bin 和 release"。

3.2 配置 JAVA_HOME 与 PATH：三个最容易写错的路径

三个路径错误，占了这类环境问题的大半。

第一个错：JAVA_HOME 指到了 bin。写成D:\dev\graalvm\graalvm-jdk-17\bin，java -version居然还能跑，因为 PATH 里加的也是这个 bin，但 native-image 和 gu 这类工具会去%JAVA_HOME%\lib找模块，路径一错就报 Could not find or load main class。

第二个错：JAVA_HOME 带了引号或者尾部反斜杠。有人习惯写"D:\dev\graalvm\graalvm-jdk-17\"，引号被当成值的一部分，尾部反斜杠还会把后面的路径转义掉，最终拼出来的 PATH 是个畸形串。

第三个错：老 JDK 的路径没清。PATH 是从前到后匹配的，前面有一个 JDK 8 的 bin，后面加多少遍新路径都没用。

我一般的做法是先在一个临时窗口里验证，确认没问题再写死：

:: 只在当前窗口生效，关掉就没了，用来试错最安全 set "JAVA_HOME=D:\dev\graalvm\graalvm-jdk-17" set "PATH=%JAVA_HOME%\bin;%PATH%" :: 关键：where 出来的第一条必须是你刚设的那个 bin where java java -version

set的写法有两个细节：整条赋值要用一对双引号包住，防止值里的特殊字符被解释；set "VAR=value"这种把引号放外面的写法不会把引号写进值里，比set VAR="value"安全得多。

验证通过后写永久变量。这里强烈建议用系统属性面板，或者用 PowerShell 精确写某一级变量，别用setx PATH：

# 只写当前用户级，不动系统级，避免权限和合并问题 [Environment]::SetEnvironmentVariable("JAVA_HOME", "D:\dev\graalvm\graalvm-jdk-17", "User") # 读回来确认，值里不应该有引号，结尾不应该有反斜杠 [Environment]::GetEnvironmentVariable("JAVA_HOME", "User")

PATH 的追加也一样走这个接口，先把当前用户级 PATH 取出来，拼上新目录，再写回去。改完必须新开一个窗口，已经打开的 cmd 和 IDE 都不会重新读环境变量，这一点坑过太多人——在 IDEA 里改完变量重启项目还是老 JDK，因为 IDE 是从它启动时继承的环境里读的，得整个重启 IDE。

还有一个更隐蔽的坑：JAVA_HOME 写在用户变量里，PATH 写在系统变量里，然后在系统 PATH 里引用%JAVA_HOME%\bin。系统变量的展开早于用户变量，这时候%JAVA_HOME%是空串，拼出来的就是一截残缺路径。要么两个都放用户级，要么两个都放系统级，别混着来。

3.3 验证 java -version 与 native-image 是否认到

变量配完，四条命令挨个敲一遍，顺序不要跳：

where java java -version javac -version native-image --version

java -version的正常输出里应该能看到 GraalVM 字样，类似Java HotSpot(TM) 64-Bit Server VM GraalVM这样一行。如果只有 OpenJDK 字样、没有 GraalVM，说明跑的还是别的 JDK，回去看where java的第一条指向哪。

native-image --version这一步分两种情况，正好对应两代发行包：

• 如果是 graalvm-jdk-17_windows-x64_bin 这一代，native-image 默认就在 bin 目录里，直接能出版本号。
• 如果包名是更早的 graalvm-ce-java17 风格，native-image 需要单独装组件，先跑gu --version看更新器在不在，再执行gu install native-image。

gu本身报错的话，八成还是 JAVA_HOME 指错层了，因为它要靠%JAVA_HOME%\lib下的模块启动。这一步过了，第 3 章的目标就算达成，可以只跑 JVM 应用了；要用 AOT 就继续往下走。

4. 打通编译链：native-image 与 MSVC 的对接

到这一步，native-image --version能出版本号，但真拿一个类去编译，十有八九会卡在"找不到编译器"上。原因不复杂：native-image 前面那段静态分析是 Java 干的，后面把结果落成 exe 是 C 工具链干的，中间这座桥得自己搭。

4.1 为什么必须装 Visual Studio Build Tools

native-image 在 Windows 上最终产物是一个 PE 格式的可执行文件，它需要三样东西：C 编译器 cl.exe、链接器 link.exe、以及 Windows SDK 里的头文件和导入库（kernel32.lib、user32.lib 这一类）。这三样东西不属于 JDK，也不会随 GraalVM 一起发下来，必须单独装。

装完整 IDE 没必要，装 Build Tools 就够。安装时勾选"使用 C++ 的桌面开发"这一个工作负载，右侧默认会带两样关键组件：MSVC 生成工具（v143 对应较新的版本，v142 对应上一代）和 Windows SDK。这两个都得在，只勾编译器不勾 SDK，链接阶段会报找不到 kernel32.lib。

安装路径我一般会改到D:\BuildTools这种短路径。默认路径带空格和括号，虽然大多数情况下能正常工作，但在批处理里调用 vcvars 脚本时，引号嵌套多了容易出错，改短路径一劳永逸。安装包本身有几个 G，装之前把实时扫描关掉会快不少，装完再开回来。

4.2 用 x64 Native Tools 命令行核对 cl.exe

装完之后不要急着在普通 cmd 里跑 native-image，先确认编译器能被调起来。开始菜单里搜 "x64 Native Tools Command Prompt"，用这个窗口，它启动时会自动把 MSVC 的环境变量铺好。进去之后：

:: 三条都要有输出，缺一条就是组件没装全 where cl where link cl

cl单独敲会打印版本横幅然后等你输入源文件，看到横幅按 Ctrl+C 退出来就行。where cl的第一条应该指向 Build Tools 目录下的VC\Tools\MSVC\...\bin\Hostx64\x64，注意结尾是Hostx64\x64，如果是Hostx86\x64或者别的组合，说明进错窗口了。

不用开始菜单也行，手动 call 一次环境脚本，效果一样：

:: 路径按实际安装位置替换，关键是最后一段必须是 vcvars64.bat call "D:\BuildTools\VC\Auxiliary\Build\vcvars64.bat" :: 调用完再验证 where cl

这里唯一要记死的是不能写成vcvars32.bat。32 位环境里的 cl 生成的是 x86 目标文件，而 GraalVM 要的是 x64，最后链接会甩你一句机器类型冲突，报错信息里全是 LNK1112，跟 JDK 一点关系都没有，新手很容易往 Java 那边查。

还有一点：这个窗口的环境是一次性的，关掉就没了。所以要么每次编译前开一次 Native Tools 窗口，要么在普通 cmd 里先 call 一次 vcvars64。我见过有人在 Native Tools 窗口里配好了 JAVA_HOME，兴冲冲关掉窗口重开一个普通 cmd，然后报找不到编译器，以为是变量没保存——其实是编译环境没了。

4.3 native-image 参数与第一个 hello world 编译

环境齐了，拿最小的例子验证一遍。先写一个不依赖任何第三方库的类：

// Hello.java，故意不写 package，避免第一次就踩类路径的坑 public class Hello { public static void main(String[] args) { System.out.println("hello from native image"); System.out.println("java.version=" + System.getProperty("java.version")); } }

编译分两步，先 javac 出 class，再 native-image 出 exe：

:: 在 Native Tools 窗口里执行，工作目录随便建一个英文路径 cd /d D:\work\hello javac Hello.java :: --no-fallback 让构建失败时直接报错，而不是悄悄生成一个壳 native-image --no-fallback -J-Xmx4g -o hello.exe Hello

几个参数值得说清楚：

--no-fallback是最该加的一个。不加的话，静态分析遇到搞不定的地方，native-image 会退而求其次生成一个仍然依赖 JVM 的启动器，你以为编译成功了，拿到别的机器上一跑发现要装 JDK，白高兴一场。加上这个参数，问题会在构建阶段暴露。

-J-Xmx4g是传给构建过程本身那个 JVM 的堆上限，注意是-J开头，不是-Xmx。中型项目不加这个很容易 OOM，报错信息里带 OutOfMemoryError，看着像 JDK 崩了，其实是构建期内存不够。

-o hello.exe指定输出文件名，不指定的话默认按主类名生成，Windows 上是hello.exe，文件名大小写不敏感所以不用纠结。

构建成功的标志是最后一行类似Finished generating 'hello' in ...。产物大小一般在十几兆，比想象中大，因为它把运行时的必要部分都塞进去了。直接双击或者命令行跑hello.exe，输出两行，第二行的 java.version 应该和java -version对得上。

如果项目里用了反射、动态代理、序列化框架，光靠静态分析会漏，得让 agent 先跑一遍收集配置：

:: 用 agent 跑一遍应用的典型路径，把反射配置吐到指定目录 java -agentlib:native-image-agent=config-output-dir=src\main\resources\META-INF\native-image ^ -jar target\app.jar

跑完目录里会多出 reflect-config.json、resource-config.json 之类的文件，打包时带进去，native-image 才知道哪些类要保留。这一步不是必须的，但只要你的应用不是纯裸写，早晚会用上。

5. 避坑与排查：五个装完跑不起来的现场

这一章的五条，全部来自真实踩过的现场，按现象、原因、解决三段写。遇到问题先在这里对一遍，能省掉大量瞎猜。

5.1 现象：java -version 出来的是老版本

现象很直接：明明 PATH 里加了新目录，java -version打出来的还是 JDK 8 那一套，连 GraalVM 字样都没有。更迷惑的是javac -version可能反而是对的，因为两个 JDK 的 bin 目录都在 PATH 里，只是顺序不同。

原因是 PATH 从前向后匹配，第一个命中的就赢了。老 JDK 的路径要么还在 PATH 里，要么在新路径之前。IDE、终端、系统服务各自继承的环境还可能不一样，所以在 IDEA 的终端里正常、在系统 cmd 里不正常，这种情况很常见。

解决方式是先用where java把所有候选列出来，看清楚第一条是谁，然后把老路径从对应的变量级别里删掉，而不是在后面继续追加。追加再多也没用，前面的永远优先。改完必须开新窗口，已经打开的窗口读的还是旧环境。

5.2 现象：gu 或 native-image 报 Could not find or load main class

报错里会出现一长串类名，然后跟一句 Could not find or load main class，看起来像 jar 包损坏。实际上 bin 目录下的java.exe是能跑的，坏的是那些依赖模块路径的工具。

原因是 JAVA_HOME 指到了 bin 那一层，或者带了引号、尾部反斜杠。这些工具启动时要靠%JAVA_HOME%\lib去找模块，路径拼错就找不到。

解决办法是把 JAVA_HOME 改回解压出来的根目录，用echo %JAVA_HOME%看一眼实际值，确认没有引号、结尾没有反斜杠、最后一段不是 bin。改完重开窗口再试。

5.3 现象：链接报 LNK1104，找不到 kernel32.lib

构建跑到一多半，前面静态分析全过，最后链接阶段甩一句LINK : fatal error LNK1104: cannot open file 'kernel32.lib'，前面几分钟的等待全废。

原因有两个。一是在普通 cmd 里直接跑了 native-image，MSVC 环境根本没加载，cl 和 link 都是碰运气找到的，SDK 的库目录压根没进 LIB 环境变量。二是装 Build Tools 时只勾了编译器，没勾 Windows SDK，机器上确实没有这个 lib。

解决：确认在 Native Tools 窗口里操作，或者先 call 一次 vcvars64.bat；如果环境没问题还报，回去打开安装程序，把 Windows SDK 那一项补勾上，重装一遍。

5.4 现象：链接报 LNK1112，机器类型冲突

报错原文里会写 module machine type 'x86' conflicts with target machine type 'x64'。看到这个基本可以断定是编译器和目标架构对不上。

原因是进了 x86 的 Native Tools 窗口，或者 call 的是 vcvars32.bat。这两个环境里的 cl 生成 32 位目标文件，而 GraalVM 要的是 64 位，链接器直接拒绝。

解决很机械：换 x64 那个窗口，或者把 call 的脚本名改成 vcvars64.bat，然后where cl确认路径里是 Hostx64\x64。这条错误最容易误导人往 JDK 版本上查，其实跟 Java 一点关系没有。

5.5 现象：执行过 setx PATH 之后系统命令全没了

这是最严重的一条。有人为了图省事，直接setx PATH "%PATH%;D:\dev\graalvm\graalvm-jdk-17\bin"，重启之后发现 ping、ipconfig 全找不到，甚至开始菜单里一些程序也起不来。

原因有两层。一是%PATH%在 setx 执行时已经被展开成当时窗口里的值，而那个值往往是用户 PATH 和系统 PATH 拼起来的合并结果，写回去等于把系统级的内容灌进了用户级。二是 setx 对值的长度有上限，超过会被截断，PATH 一截断，后半段全丢。

解决：先用系统属性面板把 PATH 恢复成默认值，或者手动把系统级 PATH 重建一遍。之后改 PATH 一律用 PowerShell 的[Environment]::SetEnvironmentVariable(..., "User")，先把原值取出来做字符串拼接，再写回去，绝不用 setx 直接动 PATH。

6. 装完怎么验证：四条命令加一次最小 AOT 编译

环境配完，我不太相信"看起来能跑"这件事。翻过一次车之后，我养成了固定走一遍验证清单的习惯，前后不到三分钟，但能把后面几天的排查时间省下来。

先看四条命令的输出特征，逐条对：

然后做一次端到端的编译验证，这一步才是真正能证明环境可用的：

@echo off REM verify.cmd，放在任意英文路径下，双击运行 setlocal echo [1/4] 检查 JAVA_HOME echo %JAVA_HOME% if not exist "%JAVA_HOME%\bin\javac.exe" ( echo FAIL: JAVA_HOME 没有指向 JDK 根目录 exit /b 1 ) echo [2/4] 检查编译器 where cl >nul 2>&1 if errorlevel 1 ( echo FAIL: cl.exe 不在 PATH 里，先 call vcvars64.bat exit /b 1 ) echo [3/4] 编译一个最小类 if not exist "%~dp0Hello.java" ( echo FAIL: 同目录下缺 Hello.java exit /b 1 ) javac -d "%~dp0out" "%~dp0Hello.java" || exit /b 1 echo [4/4] 生成原生可执行文件 native-image --no-fallback -o "%~dp0hello.exe" -cp "%~dp0out" Hello || exit /b 1 echo 构建完成，运行结果： "%~dp0hello.exe" endlocal

这个脚本的四步对应四类故障：第一步卡 JAVA_HOME，第二步卡编译链，第三步卡 JDK 本身，第四步才会暴露反射配置、资源缺失这类应用层问题。setlocal保证脚本里改的变量不外泄，%~dp0让脚本在任意工作目录下都能找到同级文件，|| exit /b 1保证任一步失败就停，不会带着错误继续往下跑出一堆假象。

跑通之后，我还习惯多做一件事：把生成的 exe 复制到一个没装 JDK 的目录里单独运行。这一步能验证产物是不是真的自包含。如果它一跑就报找不到 JVM，说明构建时没加--no-fallback，编出来的是个壳，前面所有验证都白做。这个动作花十秒钟，但能挡住把壳当成品发出去的尴尬。

还有一个容易被忽略的点是产物的一致性。同一个类，在 Native Tools 窗口里编和在普通 cmd 里编，如果后者也能过，说明 vcvars 的环境被永久写进了系统变量，这本身不算错，但会让环境变得不可控——换台机器就复现不出来。我倾向于保持"环境是一次性加载"的习惯，构建脚本里显式 call 一次 vcvars64，而不是依赖系统变量里长期躺着的 LIB 和 INCLUDE。

从那以后我每次装 GraalVM，不管是 17 还是别的版本，都强制走一遍这四条命令加一个最小类编译，哪怕只是帮同事配个环境也一样。因为环境问题的可怕之处不在于它难，而在于它总是延后爆炸——java -version是好的，写一周代码也没事，等到要出包那天才发现 native-image 从来没通过。希望帮到你。

本文还有配套的精品资源，点击获取