必须装JDK 11或17、sbt≥1.9.0、Metals插件，三者缺一不可；其他Scala插件须全禁用，否则跳转失效、补全卡顿；Java版本必须严格匹配，build.sbt中必须显式声明scalaVersion和javacOptions，修改后需手动执行Metals: Import build。
必须装 JDK 11 或 17、sbt ≥1.9.0、Metals 插件，三者缺一不可；其他 Scala 相关插件（如 Scala Syntax）全得禁用，否则跳转失效、补全卡顿是常态。
Java 版本必须严格匹配 JDK 11/17
Metals 在 2026 年 4 月仍不支持 JDK 21+，JDK 8/11 混用或 JDK 21 装了就卡在 “Starting Metals…”。验证方式只有这一种：java -version 输出里必须含 11.0. 或 17.0.。
- Windows 用户常漏配
JAVA_HOME环境变量——只装了 JDK 不等于系统能识别它；路径要填完整，比如C:\Program Files\Java\jdk-17.0.2 - macOS/Linux 用户别信
/usr/bin/java，它大概率是 JRE；用/usr/libexec/java_home -v 17查真实路径，再填进 VSCode 设置里的metals.javaHome - VSCode 设置中显式指定
metals.javaHome是最稳做法，比依赖系统 PATH 更可靠
build.sbt 里两行配置不能省
哪怕你用 sbt new scala/hello-world.g8 生成项目，build.sbt 默认也不带关键声明，Metals 会直接报 No scala version found for project。
- 必须写死
scalaVersion := "3.3.3"（或你实际用的稳定版），不能写"3"或留空——Metals 解析器不猜版本 - 加上
javacOptions ++= Seq("-source", "17", "-target", "17")，否则 JDK 17 编译出的 class 文件可能被误判为不兼容 - Scala 3 项目别混用
sbt-scala-module这类 Scala 2 插件，它们会静默让 given/using 语法不识别
导入失败别瞎点 “Reload window”
点击 Import build 后卡住、日志里反复出现 Failed to connect to build server，90% 是本地状态脏了，不是网络问题。
- 删掉项目根目录下的
.metals和target目录，再重启 VSCode —— 这比反复重载窗口快得多 - 终端进项目根目录，手动跑一次
sbt compile；若它失败，Metals 必定失败，别绕过这步 - 检查 VSCode 设置里
metals.serverVersion的值是不是具体版本号（如0.11.12），别设成latest—— 自动拉 latest 容易因网络波动拉到损坏包
插件冲突比配置错误更常见
很多人装完 Metals 还顺手装了 “Scala Syntax”、“Scala (sbt)”、“Scala Debugger”，结果跳转失效、补全延迟、右键菜单消失——这些插件和 Metals 不兼容，且不会报错，只会悄悄抢资源。
- 打开 VSCode 扩展面板，搜 “scala”，把除
scalameta.metals外所有插件全部禁用 -
build.sbt修改后，必须手动执行Metals: Import build（Ctrl+Shift+P），Metals 不监听文件变化自动重载 - 打开
.scala文件时右下角语言模式要是Scala (Metals)，不是Scala或Plain Text；点它手动切过去
最容易被忽略的是：Metals 导入过程本质是启动一个后台 sbt 进程并建立 BSP 连接，它完全不读你的 IDE 主题、字体设置或快捷键绑定，只信任 build.sbt 和 JAVA_HOME。任何“看着正常但功能不对”的情况，先查这两样。
