必须装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。

VSCode

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

下载

• 必须写死 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。任何“看着正常但功能不对”的情况，先查这两样。