调试失败时须先确认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 服务。正确做法是：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 确保文件已保存（.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，否则新选项不会生效——静态解析不触发重载，这点特别容易被忽略。