Metals插件安装后必须配置Java 17路径、提供有效build.sbt文件并手动执行Import build三步，缺一不可；VSCode不自动识别JDK，需在settings.json中显式设置metals.javaHome，且须确保.scala文件语言模式为“Scala (Metals)”。
Metals 插件不能单独安装就用，必须搭配 Java 17、sbt 和有效的 build.sbt 才能启动语言服务；点“安装”只是第一步，后续三步缺一不可。
Java 17 必须手动指定路径，VSCode 不会自动识别
Metals 启动失败最常见原因就是 metals.javaHome 没设或设错。VSCode 不读系统 JAVA_HOME，也不自动扫描 JDK 安装目录。
- 终端运行
java -version确认输出含17.x.x（不是1.8或11.0.x） - 用
/usr/libexec/java_home -v 17（macOS）或update-java-alternatives -l（Ubuntu）查真实路径 - 在 VSCode 设置中搜索
metals java home→ 点“编辑 settings.json” → 加这行："metals.javaHome": "/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home"（Windows 路径用双反斜杠，如"C:\Program Files\Java\jdk-17"） - 改完保存，重启 VSCode 窗口（不是仅重载）
build.sbt 是硬门槛，空项目或裸 .scala 文件不触发导入
Metals 不分析单个文件，只响应构建定义。没有 build.sbt，状态栏永远不显示 “Import build?” 提示。
- 项目根目录下必须有
build.sbt，哪怕只写一行：ThisBuild / scalaVersion := "3.3.3" - 别用
project/Build.scala替代 —— Metals 对 sbt 1.x 的 DSL 支持不稳定，优先用 .sbt 格式 - 如果已有项目但没
build.sbt，不要直接打开src/子目录，必须打开包含该文件的最外层文件夹 - 手动触发导入：按
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://maven.aliyun.com/repository/public"]
最容易被忽略的是：导入成功后右下角显示 Metals (ready)，但如果你打开的 .scala 文件右下角语言模式仍是 Plain Text 或 Scala（没带 (Metals)），所有功能都不会生效 —— 务必点击右下角语言标识，手动选一次 Scala (Metals)。
