调试失败时须先确认Metals真正就绪：JDK 11/17已安装并显式配置metals.javaHome，项目根目录有含scalaVersion和-source:3的build.sbt，删.metals/target后执行Import build直至状态栏显示“Metals: Ready”，再通过右键Debug启动。
调试失败时先确认 Metals 是否真正就绪
VSCode 里点“运行”或“调试”没反应、断点不命中、提示 No main class found，大概率不是配置少了一步，而是 Metals 根本没完成初始化。状态栏显示 (connecting) 或一直卡在 Starting Metals…，说明语言服务器压根没起来——这时候调任何调试设置都白搭。
必须满足三个硬条件才可能进入调试流程：
-
java -version输出含11.0.或17.0.（JDK 21 尚未被 Metals fully support） - VSCode 设置中显式填了
metals.javaHome绝对路径，不能留空或依赖系统PATH - 项目根目录有
build.sbt，且里面写了scalaVersion := "3.3.3"和javacOptions ++= Seq("-source", "17", "-target", "17")
缺一不可。删掉 .metals 和 target 目录后重启 VSCode，再手动执行 Metals: Import build，等状态栏变成 Metals: Ready 才算真正就绪。
main 方法必须符合 sbt 的约定路径和命名
VSCode 不扫描整个项目找 def main，它靠 sbt 的 run 任务启动，而该任务只认两个地方：
-
src/main/scala下的顶层object，名字需与文件名一致（比如HelloWorld.scala里必须是object HelloWorld） - 该
object内必须有def main(args: Array[String]): Unit方法 - 不能放在
src/test/scala或任意子包里——除非你在build.sbt中显式配置mainClass := Some("com.example.HelloWorld")
常见错误：把 App trait 当作万能写法。虽然 object HelloWorld extends App 能编译，但部分 Metals 版本（如 0.11.12）对 App 的入口推断不稳定，建议优先用显式 main 方法。
调试配置要绕过 launch.json 直接用 Metals 内置支持
别手动建 .vscode/launch.json 并填 type: "scala"——VSCode 官方没提供原生 Scala 调试器，所有“调试”能力实际来自 Metals 启动的 BSP 服务。正确做法是：
- 确保文件已保存（
.scala文件未保存时断点不会激活） - 右键点击编辑器内任意位置 → 选
Debug 'HelloWorld'（名称来自 object 名） - 或按
Ctrl+Shift+D切到调试视图，点击左上角绿色三角形（前提是当前打开的是合法的主类文件） - 首次调试会自动生成临时
.vscode/tasks.json，内容基于 sbt 的run任务，不要手动改它
如果右键菜单没出现 Debug 项，说明 Metals 没识别出可执行入口——回到前两步检查路径、命名、build.sbt 声明是否全部合规。
Scala 3 新语法调试时容易忽略的编译器开关
用 given、enum、inline 等语法写的代码，在调试时断点标红或跳转失效，往往不是调试器问题，而是编译器没启用对应模式。必须在 build.sbt 中加：
scalacOptions ++= Seq( "-source", "3", "-Ykind-projector" )
同时 VSCode 设置里也要补上：
-
metals.scalacOptions加-source:3（注意冒号不是等号） - 禁用所有非 Metals 的 Scala 插件，尤其是
Scala Syntax和Scala Debugger，它们会劫持语言模式，让编辑器误判为 Scala 2
改完 build.sbt 后，必须手动执行一次 Metals: Import build，否则新选项不会生效——静态解析不触发重载，这点特别容易被忽略。
