Metals导入失败时应检查三件事：JDK版本是否为11–17（java -version验证）、sbt版本是否与project/build.properties一致、JAVA_HOME是否正确指向JDK根目录；确认后删掉.metals/和target/，重启VS Code并手动执行Metals: Import build。
Metals导入失败时该检查什么
VS Code 里 Scala 项目卡在 Importing build 或状态栏不显示 Metals: Ready，90% 是构建链路没对齐，不是插件坏了。关键要确认三件事是否同时满足：
-
java -version输出的是 JDK 11–17（JDK 21 或 8 都可能静默失败） -
sbt --version和项目project/build.properties中声明的 sbt 版本一致（比如项目锁了sbt.version=1.9.9，你装了 sbt 2.x 就不会连上） -
JAVA_HOME指向 JDK 根目录（Windows 下不能是jre/子目录，也不能带末尾反斜杠）
验证完后，删掉项目根目录下的 .metals/ 和 target/，重启 VS Code，再手动执行 Metals: Import build。
调试断点不生效的典型原因
Scala 断点不命中，尤其在 Spark 项目里，大概率不是配置错，而是运行模式不对：
- 本地调试 Spark 必须用
local[*]模式启动，否则 JVM 进程跑在远程 executor 上，VS Code 调试器根本连不上 - 确保
launch.json中mainClass指向的是含main方法的对象，不是 trait 或普通 class - Scala 3 项目必须显式在
build.sbt里写scalaVersion := "3.3.3"，否则 Metals 可能按 Scala 2 解析，导致符号索引错乱
示例正确配置片段：
{
"type": "scala",
"request": "launch",
"name": "Run Main",
"mainClass": "com.example.App",
"args": [],
"env": {
"SPARK_MASTER": "local[*]"
}
}
补全/跳转失效后怎么快速恢复
改完 build.sbt 后代码没提示、F12 跳不到定义，不是插件崩溃，是 Metals 的语义索引没更新：
- 保存
build.sbt后，必须手动触发Metals: Import build（Ctrl+Shift+P），它不会自动监听文件变更 - 避免在
build.sbt里写动态逻辑（如sys.process调外部命令、读文件生成版本号），Metals 解析器不执行代码，这类内容会被跳过 - 如果跳转仍失败，先确认当前文件是否被 Metals 识别为 Scala —— 状态栏右下角应显示
Scala，不是Plain Text
真正提升 Scala 编码效率的快捷键组合
Scala 写法密集、嵌套多，光靠通用快捷键不够，得搭配 Metals 特有操作：
-
Alt+F12：查看某符号所有引用位置（比 Ctrl+Shift+O 更聚焦，适合查map、flatMap在哪被重载） -
Ctrl+.（句点）：光标停在报错红波浪线下，弹出快速修复菜单，自动补 import 或展开隐式转换 -
Ctrl+Shift+P→ 输入Metals: Run doctor：一键诊断环境问题，比翻日志快得多 -
Ctrl+D配合Ctrl+Shift+L：选中一个 case class 字段名，连按两次Ctrl+D选中所有同名字段，再Ctrl+Shift+L全选所有匹配项，批量加val或改类型
复杂点在于：Metals 的功能深度依赖 sbt 构建结果，而 sbt 构建又强耦合 JDK 和 Scala 版本。一旦其中一环偏离推荐范围，表现就是“看起来能用，但总差一口气”——比如跳转偶尔失效、补全漏方法、调试断点飘移。这种问题没法靠重装插件解决，只能回到构建链路本身去对齐。
