metals卡在starting metals…或importing build…主因是jdk/sbt版本错配、网络阻塞或静态解析失败；须显式配置metals.javahome指向jdk 17绝对路径、确保sbt≥1.9.0且与项目匹配、删.metals/重试导入，并查metals日志确认bsp连接是否建立。
Metals 启动卡在 Starting Metals… 或长时间停留在 Importing build…，不是插件坏了，而是构建链路某处断了——90% 的问题出在 JDK/sbt 版本错配、网络源阻塞或静态解析失败，跟 VSCode 本身无关。
为什么 Metals 卡在 Starting Metals…？
这个状态代表 Metals 还没连上 sbt 启动的构建服务器（BSP），根本原因通常是底层 JVM 环境或启动器下载失败：
-
java -version显示 JDK 17，但 VSCode 没用它：必须显式配置metals.javaHome，不能只靠系统环境变量 - JDK 21 或 JDK 8 被悄悄加载：Metals 当前（2026 年 6 月）稳定支持仅限 JDK 11–17；JDK 21 会导致 BSP 启动静默失败
- Metals Launcher 下载被墙：首次启动需从 GitHub Releases 下载
metals-launcher.jar，国内用户常卡在这一步 - Windows 用户填了带尾部反斜杠的路径（如
C:\Program Files\Java\jdk-17\）：VSCode 解析失败，直接跳过
Importing build… 卡住或超时的真正原因
这不是“导入慢”，而是 Metals 尝试调用 sbt 启动 BSP 时被阻断，常见于：
- sbt 版本与项目不兼容：项目
project/build.properties锁定sbt.version=1.9.9，你本地装的是 sbt 2.x → 静默拒绝连接 - build.sbt 含运行时逻辑：比如
sys.env.get("CI")或scala.util.Properties.isWin→ Metals 只做静态解析，直接跳过整段，导致模块识别为空 - 国内源未配置：sbt 默认走 Maven Central 和 GitHub，依赖下载速度低于 10 KB/s 时，BSP 等待超时（默认 300 秒）后退出
- 项目根目录存在残留的
.metals/或.bloop/：旧缓存可能含损坏的 BSP 描述符，导致新导入反复失败
如何快速验证 Metals 是否真连上了？
别只看状态栏文字，用终端和日志交叉确认：
- 打开 VSCode 输出面板 → 切换到
Metals日志页，搜索BSP connection established；没这行就说明没连上 - 终端进项目根目录，手动执行
sbt metalsEnable，观察是否报错（如command not found是 sbt 未安装，Unsupported Scala version是版本冲突） - 右下角显示
Scala (Metals)≠ Metals 在工作：必须打开一个.scala文件，看是否有类型提示、Ctrl+Click跳转是否生效 - 删掉
.metals/后重试导入，比重启 VSCode 更有效；但别删project/target/，那是 sbt 自己的缓存
最易被忽略的点：Metals 不是“装完即用”的 IDE，它是桥接器——一边靠 sbt 启动 BSP，一边靠 JDK 加载服务。任何一端版本或路径偏差，都会让桥断在中间，而错误日志往往藏在输出面板第三页之后。
