Java调试失败主因是JDK路径错误、项目未识别为Java工程、mainClass与classpath不匹配；需确认java.home指向JDK根目录、创建标准项目结构、正确配置全限定类名及vmArgs参数。
Java Extension Pack 装不全，java.home 就永远配不对
VSCode 本身不带 Java 运行时，装了插件却跑不起来，八成是 java.home 指向了空目录、JDK 的 JRE 子目录，或者压根没装 JDK。Extension Pack 里 Red Hat Java（也就是 vscode-java）依赖真实 JDK，不是 JRE —— 它要编译、启动语言服务器，缺 javac 和 jdk.jshell 模块直接报错。
- 先在终端执行
java -version和which java（macOS/Linux）或where java（Windows），确认系统已安装 JDK 17+（推荐 JDK 17 或 21，避免用 JDK 8 或 22+ 的预发布版） - 打开 VSCode 设置（
Cmd+,或Ctrl+,），搜java.home，填入 JDK 根目录路径，比如：/Library/Java/JavaVirtualMachines/jdk-17.0.1.jdk/Contents/Home（macOS）、C:\Program Files\Java\jdk-17.0.2（Windows） - 别填到
.../jre或.../bin下；如果路径含空格或中文，不用加引号，但必须是完整、可读的目录 - 改完后重启 VSCode —— 插件不会热重载 JDK 配置
运行单个 .java 文件时提示 “Cannot resolve module”，其实是没建项目结构
VSCode 的 Java 插件默认按 Maven/Gradle 项目逻辑工作。直接右键 Run Code（来自 Code Runner）或点上方「运行」按钮，大概率失败，因为缺少 module-info.java 或 pom.xml，插件找不到 classpath。
- 临时方案：用终端手动编译运行 ——
javac HelloWorld.java && java HelloWorld，适合练手小文件 - 正规做法：用命令面板（
Cmd+Shift+P）运行Java: Create Java Project，选no build tools可生成最简结构（含src目录和.classpath），之后所有.java放src下就能被识别 - 如果已有旧项目，确保根目录有
.project或pom.xml；否则插件会当成普通文件夹，不激活 Java 功能
调试时断点灰色、不命中，十有八九是 launch.json 的 mainClass 写错了
VSCode 调试 Java 不像 IntelliJ 那样自动推导入口类。断点变灰、控制台只输出“Listening on port…”然后卡住，基本是 launch.json 里 mainClass 值和实际类名对不上，或者类不在 classpath 中。
-
mainClass必须写全限定名，比如com.example.HelloWorld，不能写HelloWorld或./HelloWorld - 类必须已编译（
.class文件存在），且所在包路径与目录结构严格一致（com/example/HelloWorld.class必须在out/production/src或target/classes下） - 如果项目用了模块（
module-info.java），launch.json还得加上"vmArgs": "--module-path ${workspaceFolder}/out/modules --add-modules ALL-SYSTEM"这类配置，否则模块找不到主类 - 检查调试控制台顶部是否显示
Starting Debug Session...后立刻变成Debug session terminated—— 这是 VM 启动失败，优先看console输出里的NoClassDefFoundError或ClassNotFoundException
Mac 上调试闪退、Windows 上中文乱码，根源都在 JVM 启动参数
VSCode 调试器底层调的是 java 命令，但默认没传 -Dfile.encoding=UTF-8 或 -XstartOnFirstThread，导致跨平台行为不一致。
立即学习“Java免费学习笔记（深入）”；
- Mac：GUI 程序（如 Swing）调试崩溃，加
"vmArgs": "-XstartOnFirstThread"到launch.json的配置里 - Windows 控制台中文输出为
???：在launch.json的vmArgs加-Dfile.encoding=UTF-8，同时确认终端字体支持 UTF-8（如 Windows Terminal 设置为“等宽字体”） - Linux 下偶尔因 GTK 版本冲突无法显示 Swing 组件，可加
-Djdk.gtk.version=2降级兼容 - 这些参数只影响当前调试会话，不影响编译；不要写进
java.compile.additionalArguments，那是给javac用的
mainClass 和 classpath 能不能对上号。其他都是这三件事的衍生问题。 
