先说一个很多人踩过的坑：Metals 可不是装上就能用的，它是个“娇气”的插件——Ja va 17、sbt 和 build.sbt 三者缺一不可。

点“安装”只是走完了流程的第一步。真正要让它跑起来，后面还有三步硬性操作等着你。

Ja va 17 路径必须手动指定，VSCode 不会自动帮你找

Metals 启动失败，十有八九是 metals.ja vaHome 没配对。

VSCode 不会读取系统的 JA VA_HOME 环境变量，也不会自动扫描你装过哪些 JDK。这条路径必须你亲手写进去。

• 先在终端跑一下 ja va -version，确认输出是 17.x.x，而不是 1.8 或 11.0.x
• 用 /usr/libexec/ja va_home -v 17（macOS）或者 update-ja va-alternatives -l（Ubuntu）查到 JDK 的真实路径
• 在 VSCode 设置里搜 metals ja va home，点“编辑 settings.json”，加上这一行：
  "metals.ja vaHome": "/Library/Ja va/Ja vaVirtualMachines/jdk-17.jdk/Contents/Home"
  Windows 用户路径里的反斜杠要写成双反斜杠，例如 "C:\Program Files\Ja va\jdk-17"
• 改完保存，重启 VSCode 窗口。注意是整个窗口，不是仅重载页面

build.sbt 是硬门槛，空项目裸文件不会触发导入

Metals 不是文本编辑器级别的工具，它只识别构建定义。

如果项目根目录下没有 build.sbt，它永远不会有反应，状态栏也不会弹出“Import build”的提示。

• 项目根目录下必须有一个 build.sbt，哪怕内容只有一行：
  ThisBuild / scalaVersion := "3.3.3"
• 别想着用 project/Build.scala 替代，Metals 对 sbt 1.x 的 DSL 支持不太稳定，.sbt 格式是最稳妥的选择
• 如果已经有项目结构但缺少 build.sbt，千万不要直接打开 src/ 子目录，一定要打开包含 build.sbt 的那个最外层文件夹
• 想手动触发导入？按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Win/Linux），输入 Metals: Import build，回车即可

导入卡住或失败？先看日志，再删缓存

导入过程中如果卡在“Compiling…”不动，或者报错说“Failed to connect to build server”，大概率不是配置写错了。

更常见的原因是依赖下载失败，或者索引文件坏了。

• 点一下 VSCode 右下角的 Metals (connecting...) 或 Metals (failed)，弹出的日志面板里重点找以 [ERROR] 开头的行
• 常见的坑：Could not resolve dependency（很大可能是国内网络问题）、Unsupported Scala version（build.sbt 里写了 2.11.x 这种早就被抛弃的版本）
• 临时救急方案：删掉项目根目录下的 .metals/、.bloop/ 和 target/，再重新执行 Metals: Import build
• 长期来看，建议在 settings.json 里加上国内的镜像源：
  "metals.customRepositories": ["https://ma ven.aliyun.com/repository/public"]

最后一个容易忽略的细节

导入完成后，右下角显示 Metals (ready) 只是第一步。

如果你打开的 .scala 文件右下角语言模式仍然是 Plain Text，或者普通的 Scala（不带 (Metals)），那所有功能都不会生效。

务必点一下那个语言标识，手动选一次 Scala (Metals)。

《夸克》非常好用的免费AI浏览器

下载APP查看