metals插件装不上或启动失败的根本原因是java版本不匹配（需jdk 11–17）或metals-server下载卡住；build.sbt修改后需手动执行metals: import build；scala 3项目须显式设置scalaversion并禁用scala 2插件；调试失效多因缺失调试信息或源码路径未正确配置。
Metals插件装不上或启动失败
根本原因通常是 Java 版本不匹配或 metals-server 下载卡住。Metals 要求 JDK 11–17（推荐 11 或 17），JDK 21 尚未完全支持，JDK 8 则直接拒绝启动。
- 检查当前 Java 版本：
java -version，确保输出里有11.或17. - VSCode 设置里显式指定 JDK 路径：在设置中搜索
metals.javaHome，填入完整路径，比如/usr/lib/jvm/java-11-openjdk-amd64（Linux）或C:\Program Files\Java\jdk-11.0.20（Windows） - 如果 Metals 长时间卡在 “Starting Metals…”，手动清空缓存：
rm -rf ~/.cache/metals（macOS/Linux）或删掉%LOCALAPPDATA%\Metals（Windows），再重启 VSCode - 国内用户常因 GitHub 下载慢导致失败，可提前手动下载
metals-launcher.jar，放到~/.cache/metals/对应版本目录下（路径见 VSCode 输出面板里的 Metals 日志）
build.sbt 改了但代码没提示/跳转失效
Metals 依赖 bsp 协议与构建工具通信，不是“改完就热更新”。sbt 文件变更后必须主动触发重新导入，否则符号索引仍是旧的。
- 保存
build.sbt后，按Ctrl+Shift+P（Win/macOS）或Cmd+Shift+P（macOS），输入并执行Metals: Import build - 如果项目含多模块，确认
build.sbt顶层定义了ThisBuild / scalaVersion := "2.13.12"等全局配置；局部模块没设scalaVersion会导致 Metals 推断失败，报No scala version found for project - 避免在
build.sbt中使用动态生成逻辑（如读文件、调外部 API），Metals 解析器不执行实际代码，只做静态分析，这类写法会静默跳过模块
Scala 3 项目无法识别 given/using 或枚举
不是 Metals 问题，是 sbt 插件和编译器版本没对齐。Scala 3 的新语法需要 Metals 显式启用 Scala 3 支持，并绑定对应版本的 scalac。
- 确保
build.sbt中启用了scalaVersion := "3.3.1"（或更高稳定版），且没有混用addSbtPlugin("ch.epfl.scala" % "sbt-scala-module" % "...")这类仅适配 Scala 2 的插件 - 在 VSCode 设置中打开
metals.scalacOptions，追加-source:future（如需实验性特性），但生产环境建议用稳定-source:3 - 首次打开 Scala 3 项目时，Metals 可能默认以 Scala 2 模式启动——关掉窗口，删掉项目根目录下的
.metals/和target/，再重新打开并执行Import build
调试时断点不命中或变量显示 <error></error>
本质是调试器找不到源码映射（source mapping）。Scala 编译产物（.class）需带完整调试信息，且 Metals 必须能定位到原始 .scala 文件。
- sbt 中必须启用调试信息：
Compile / compile / scalacOptions += "-g:vars,lines,source"（Scala 2）或Compile / compile / scalacOptions += "-sourcepath:src/main/scala"（Scala 3） - 确认项目结构符合约定：源码在
src/main/scala/，测试在src/test/scala/；若自定义路径（如src/main/mycode/），需在build.sbt中显式配置Compile / unmanagedSourceDirectories += baseDirectory.value / "src/main/mycode" - VSCode 调试配置选的是
Scala (Metals)类型，而不是通用Java；启动前检查左下角状态栏是否显示Metals: Ready，而非Compiling…
Metals 标签页最末尾那行日志，有没有 Import finished。没有的话，所有后续功能都是空中楼阁。
