必须装JDK 11或17、sbt≥1.9.0、Metals插件，三者缺一不可；sbt不是scala命令，后者已弃用且与Metals不兼容；Metals卡在“Importing build”或未变“Ready”，主因是JDK 21不被官方支持、sbt 2.x与Spark 3.5+项目冲突、JAVA_HOME路径错误或build.sbt中缺失显式scalaVersion。
必须装 JDK 11 或 17、sbt ≥1.9.0、Metals 插件，三者缺一不可；sbt 不是 scala 命令，后者已弃用且与 Metals 完全不兼容。
为什么 Metals 卡在 “Importing build” 或状态栏没变 “Ready”
这不是网络慢或插件没装好，而是底层工具链不匹配。Metals 启动时会调用本地 sbt 进程建立 BSP 连接，一旦任一环节失败，就会静默卡住：
-
java -version输出含21.？截至 2026 年 4 月，Metals 官方未完全适配 JDK 21，必须降级到11.0.或17.0.开头的版本 -
sbt --version是2.x？Spark 3.5+ 等主流项目仍锁死sbt.version=1.9.9，本地装了 sbt 2.x 会导致静默失败 - Windows 用户检查
JAVA_HOME是否指向C:\Program Files\Java\jdk-17这类 JDK 根目录，而非jre/子目录，也不能带尾部反斜杠 - VSCode 设置中搜
metals.javaHome，手动填入完整 JDK 路径（比依赖系统环境变量更可靠）
build.sbt 改了但补全失效、跳转报错
Metals 不监听 build.sbt 文件变更，它只在导入时做一次静态解析。改完依赖、Scala 版本或插件后，语义索引仍是旧的：
- 保存
build.sbt后，按Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入并执行Metals: Import build - 若卡住，别反复点 “Reload window”——先关 VSCode，删掉项目根目录下的
.metals/和target/，再重开并手动触发导入 - 确保
build.sbt中显式写了scalaVersion := "3.3.3"（不能写"3"或留空），否则 Metals 无法推断版本 - 避免在
build.sbt里写动态逻辑，比如sys.process调外部命令、读文件生成版本号——Metals 解析器不执行代码，这类内容会被跳过
如何让 Spark 或 Scala 3 项目正常调试
Spark 断点不生效、Scala 3 的 given/using 无法识别，本质不是 IDE 配置问题，而是运行模式或编译器绑定错误：
- Spark 本地调试必须设
spark.master = "local[*]"，不能用spark-submit；VSCode 中右键选择Run this file with Metals，或在launch.json中指定mainClass直接启动 Driver - Scala 3 项目需在
build.sbt中明确写scalaVersion := "3.3.3"，并禁用所有仅适配 Scala 2 的插件（如sbt-scala-module） - 首次打开 Scala 3 项目时，Metals 可能默认以 Scala 2 模式启动——删掉项目根目录下的
.metals/和target/，重启 VSCode 再导入 - 若要用实验性特性（如
inline def），在build.sbt加scalacOptions += "-source:future"，但生产环境请改用-source:3
最容易被忽略的是：Metals 的导入过程完全信任 build.sbt 和本地 JAVA_HOME，它不读取 VSCode 的任何其他设置。哪怕所有插件都装对了，只要 build.sbt 里漏了 scalaVersion 或 JAVA_HOME 指向了 JRE，就一定会失败。
