本文详解如何在 VSCode 中为 Java 项目启用 JDK 20 的预览特性（如虚拟线程），重点纠正 vmArgs 与 args 的误用，并提供 settings.json 与 launch.json 的完整、可运行配置方案。
本文详解如何在 vscode 中为 java 项目启用 jdk 20 的预览特性（如虚拟线程），重点纠正 `vmargs` 与 `args` 的误用，并提供 `settings.json` 与 `launch.json` 的完整、可运行配置方案。
在 JDK 20（及后续的 JDK 21+ LTS）中，虚拟线程（Virtual Threads）等关键新特性默认以预览模式（Preview Feature）发布，必须显式启用 --enable-preview JVM 参数才能使用。许多开发者误将该参数置于程序参数（args）或 settings.json 的运行时配置中，导致编译通过但运行时报错：java.lang.UnsupportedOperationException: Preview Features not enabled, need to run with --enable-preview。
根本原因在于：预览特性的启用是 JVM 启动阶段的行为，必须由 Java 调试器（JDT LS）在启动 JVM 进程时传入 --enable-preview，而非传递给用户代码本身。 因此，该参数不能写在 settings.json 的 java.configuration.runtimes 中（此处仅声明 JDK 路径与名称，不控制运行时参数），也不能放在 launch.json 的 "args" 字段（该字段对应 main(String[] args) 中的参数数组），而必须置于 launch.json 的 "vmArgs" 字段中。
✅ 正确配置如下（以 macOS 为例，路径需按实际调整）：
1. settings.json（项目级，推荐放在 .vscode/settings.json）
仅声明 JDK 路径与支持的运行时，不包含 vmargs：
{
"java.home": "/Users/rahulraj/Library/Java/JavaVirtualMachines/openjdk-20.0.1/Contents/Home",
"java.configuration.runtimes": [
{
"name": "JavaSE-20",
"path": "/Users/rahulraj/Library/Java/JavaVirtualMachines/openjdk-20.0.1/Contents/Home"
}
]
}
⚠️ 注意："default": true 和 "vmargs" 在 runtimes 数组中无效，VSCode 的 Java 扩展不识别该字段；vmArgs 必须在调试配置中指定。
2. launch.json（.vscode/launch.json）——关键！
在对应调试配置中添加 "vmArgs" 数组（注意是 vmArgs，不是 args 或 vmargs 小写）：
{
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Debug Virtual Thread",
"request": "launch",
"mainClass": "${file}",
"vmArgs": ["--enable-preview"] // ✅ 正确位置：JVM 启动参数
},
{
"type": "java",
"name": "Run App with Preview",
"request": "launch",
"mainClass": "App",
"projectName": "VirtualThread_c7b22327",
"vmArgs": ["--enable-preview"] // ✅ 同样适用于命名主类
}
]
}
3. 验证代码示例（Test.java）
public class Test {
public static void main(String[] args) {
// JDK 20+ 虚拟线程示例
Thread vt = Thread.ofVirtual()
.unstarted(() -> System.out.println("Hello from virtual thread!"));
vt.start();
try { vt.join(); } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
}
}
保存后，使用命令面板（Ctrl+Shift+P / Cmd+Shift+P）选择 Java: Debug 并运行对应配置，即可成功执行。
? 额外提示：
- 若使用 Maven/Gradle 构建，还需在 pom.xml 或 build.gradle 中显式启用预览特性（如 Maven 的 maven-compiler-plugin 配置
），否则编译阶段可能报错； - settings.json 中的全局路径（如 ~/Library/Application Support/Code/User/settings.json）不生效于项目调试，务必使用工作区级 .vscode/settings.json；
- JDK 20 已结束生命周期，强烈建议升级至 JDK 21 LTS（长期支持版，虚拟线程已转正，无需 --enable-preview），避免预览特性兼容性风险。
通过以上三步精准配置，即可彻底解决“Preview Features not enabled”错误，在 VSCode 中无缝开发和调试基于 JDK 20/21 的现代 Java 并发应用。
