Java 21虚拟线程需JDK 21+并启用--enable-preview，使用Thread.ofVirtual().start()创建，避免start/join，推荐StructuredTaskScope进行结构化并发管理。
Java 21 虚拟线程需要什么 JDK 版本和启动参数
必须用 jdk-21 或更高版本（如 jdk-21.0.1），JDK 20 及更早版本不支持虚拟线程，哪怕加了 --enable-preview 也没用。OpenJDK、Oracle JDK、Eclipse Temurin 都行，但得确认是完整构建版——某些精简版（如某些 Alpine Docker 镜像里的 jdk21-jre-headless）可能缺 java.lang.VirtualThread 类。
启动时必须显式开启预览特性：--enable-preview。虚拟线程在 Java 21 中仍是预览特性（直到 Java 22 才转正），漏掉这个参数会直接抛 UnsupportedOperationException 或连 Thread.ofVirtual() 都找不到。
- 正确启动命令示例：
java --enable-preview -jar app.jar - 如果用 IDE（如 IntelliJ），需在
Run Configuration → VM Options里手动加上--enable-preview，不能只改 Project SDK 版本 - Maven 编译也要配预览：在
maven-compiler-plugin中设<source>21</source>和<target>21</target>，并加<compilerargs><arg>--enable-preview</arg></compilerargs>
如何写第一个虚拟线程代码，避开 IllegalThreadStateException
别直接调 start() 或 join() ——虚拟线程不是传统线程，Thread.start() 会报 IllegalThreadStateException。它必须由 Thread.Builder 构造，且默认是“自动调度”模式，你只负责提交任务，不管理生命周期。
最安全的写法是用 Thread.ofVirtual().unstarted(Runnable) 或更常见的 Thread.ofVirtual().start(Runnable)：
立即学习“Java免费学习笔记（深入）”；
Thread vt = Thread.ofVirtual().start(() -> {
System.out.println("运行在虚拟线程: " + Thread.currentThread());
});
- 不要对虚拟线程调
vt.join()，它可能永远阻塞（尤其在平台线程池未配置好时）；要用vt.join(5000)带超时，或改用结构化并发（见下一条） - 避免在虚拟线程里调
Thread.sleep()或Object.wait()——虽然能跑，但会退化成挂起平台线程，失去轻量优势 - 虚拟线程默认不继承上下文类加载器，若依赖
Thread.currentThread().getContextClassLoader()，得手动传入或设置
结构化并发（StructuredTaskScope）为什么不能省
裸用 Thread.ofVirtual().start() 容易失控：异常没捕获、线程泄漏、超时难管理。Java 21 引入的 StructuredTaskScope 是唯一推荐的协调方式，它强制作用域边界和异常传播规则。
比如并发请求 3 个 HTTP 接口，用 StructuredTaskScope.ShutdownOnFailure 可确保任一失败就取消其余任务：
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
scope.fork(() -> fetchUser());
scope.fork(() -> fetchOrder());
scope.fork(() -> fetchPayment());
scope.join(); // 等全部完成或任一失败
scope.throwIfFailed(); // 抛出首个异常
}
- 必须用
try-with-resources，否则scope.close()不触发，子任务可能卡住 -
StructuredTaskScope默认使用ForkJoinPool.commonPool()调度虚拟线程，别试图换Executors.newVirtualThreadPerTaskExecutor()——它不兼容结构化语义 - 作用域内抛出的 unchecked exception 会被捕获，但 checked exception（如
IOException）需显式处理或包装，否则编译不过
常见报错：java.lang.UnsupportedOperationException: Virtual threads are not supported
这通常不是 JDK 版本问题，而是运行时环境没启用虚拟线程支持。典型场景有三类：
- Spring Boot 3.1+ 默认禁用虚拟线程，需在
application.properties加spring.threads.virtual.enabled=true，否则 WebMvc 或数据源层会静默回退到平台线程 - Tomcat/Jetty 的 Servlet 容器若未升级到支持虚拟线程的版本（如 Tomcat 10.1.12+），HTTP 请求仍跑在平台线程上，
Thread.currentThread().isVirtual()返回false - 某些监控/诊断代理（如旧版 ByteBuddy、部分 APM 工具）会拦截
Thread构造，导致虚拟线程创建失败，需检查 agent 日志是否含VirtualThread相关拒绝记录
验证是否真在虚拟线程里执行，最简单方法是加一行日志：System.out.println(Thread.currentThread().isVirtual()); ——别只看启动参数或文档，实测才是唯一标准。
