metals 是当前 vscode 中唯一能提供完整 scala 语言支持的插件，其他插件仅做基础高亮或命令封装；必须装齐 jdk 11/17、sbt ≥1.9.0、build.sbt 显式指定 scalaversion 和 javacoptions，否则导入必失败。
Metals 是当前 VSCode 中唯一能提供完整 Scala 语言支持的插件，其他插件（如 Scala Syntax、Scala (sbt)）仅做基础高亮或命令封装，无法替代它。如果你已经装了多个 Scala 相关插件，建议只保留 Metals，其余全部禁用——插件冲突是导入失败、跳转失效、补全卡顿最常见的原因。
必须装齐的三个底层组件
VSCode 本身不运行 Scala，它靠外部工具链协同工作。缺任何一个，Metals 都会卡在 “Import build” 步骤不动：
-
JDK 11或JDK 17（LTS 版本），不能用 JDK 21+（截至 2026 年 4 月，Metals官方尚未完全适配）；验证方式：java -version输出中必须含11.0.或17.0. -
sbt（≥1.9.0），不是scala命令行工具——后者已弃用且与Metals不兼容；验证：sbt --version应输出类似1.9.9 -
coursier（可选但强烈推荐），用于加速依赖下载和安装scala-cli；装完后执行cs setup可自动配置环境变量
build.sbt 里最容易被忽略的两行配置
新建项目时，很多人直接用 sbt new scala/hello-world.g8，但生成的 build.sbt 默认没指定 JVM 参数和 Scala 版本兼容性策略，会导致 Metals 启动失败或语义分析错乱：
- 必须显式声明
scalaVersion := "3.3.3"（或你实际使用的稳定版），不能留空或写成"3"——Metals无法解析模糊版本号 - 建议加上
javacOptions ++= Seq("-source", "17", "-target", "17")，否则 JDK 17 编译出的 class 文件可能被误判为不兼容 - 如果要用实验性特性（比如 inline def），再追加
scalacOptions += "-source:future"，但生产项目请改用-source:3
导入失败时优先检查这三件事
点击 “Import build” 后进度条卡住、日志里反复出现 Failed to connect to build server 或 Could not resolve dependencies，大概率不是网络问题，而是本地状态异常：
- 删掉项目根目录下的
.metals和target目录，再重启 VSCode —— 这比反复点 “Reload window” 有效得多 - 在终端进项目根目录，手动跑一次
sbt compile，看是否报错；若失败，Metals必定失败，别跳过这步 - 打开 VSCode 设置，搜
metals.serverVersion，确认值是类似0.11.12的具体版本号，而不是latest—— 自动拉 latest 容易因网络波动拉到损坏包
Metals 的导入过程本质是启动一个后台 sbt 进程并建立 BSP（Build Server Protocol）连接，它不读取你的 IDE 设置，只信任 build.sbt 和本地 JAVA_HOME。很多“配置明明对了却不行”的问题，根源都在 sbt 启动时用错了 JDK —— 检查 which sbt 对应的脚本里有没有硬编码 JAVA_HOME，比调 VSCode 设置更管用。
