必须显式配置metals.javaHome绝对路径、项目根目录含build.sbt、手动执行Metals: Import build，三者缺一不可；其他Scala插件须全禁用，否则跳转失效、补全卡顿。
装完 Metals 插件不等于能写 Scala——缺 metals.javaHome、没 build.sbt、不手动执行 Metals: Import build，三者任一缺失都会卡在 “Starting Metals…” 或状态栏一直显示 “(connecting)”。
metals.javaHome 必须显式填绝对路径，VSCode 不读 JAVA_HOME
哪怕终端里 java -version 输出是 17.0.2，VSCode 仍可能用错 JVM。它既不读系统 JAVA_HOME，也不自动扫描 JDK 安装目录。
- 先确认真实路径：
/usr/libexec/java_home -v 17（macOS）、update-java-alternatives -l（Ubuntu）、或 Windows 的C:Program FilesJavajdk-17 - 打开 VSCode 设置 → 搜索
metals java home→ 点“Edit in settings.json” → 加这行："metals.javaHome": "/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home" - Windows 路径要用双反斜杠：
"metals.javaHome": "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替代——sbt 1.x 对 DSL 支持不稳定，优先用.sbt格式 - 多模块项目：必须在顶层
build.sbt中设ThisBuild / scalaVersion，不能只在子项目里写scalaVersion - Scala 3 项目要加
metals.scalacOptions配置项："-source:3"，否则given、enum全标红
导入失败别瞎点 “Reload window”，先清缓存再重试
点击 Metals: Import build 后卡住、日志里反复出现 Failed to connect to build server 或 Could not resolve dependency，90% 是本地状态脏了，不是网络问题。
- 删掉项目根目录下的
.metals/、.bloop/和target/ - 终端进项目根目录，手动跑一次
sbt compile；若它失败，Metals 必定失败 - 检查
settings.json中metals.serverVersion是否为具体版本号（如"0.11.12"），别设成"latest" - 国内用户可加镜像源加速：
"metals.customRepositories": ["https://maven.aliyun.com/repository/public"]
插件冲突比配置错误更常见，其他 Scala 插件必须全禁用
装了 Scala Syntax、Scala (sbt)、Scala Debugger 等插件后，跳转失效、补全卡顿、右键菜单消失——这些插件和 Metals 不兼容，且不会报错，只会悄悄抢资源。
- 打开 VSCode 扩展面板，搜 “scala”，把除
scalameta.metals外所有插件全部禁用 - 确保
.scala文件的语言模式是 “Scala (Metals)”，不是 “Scala” 或 “Plain Text” - 修改
build.sbt后，必须手动触发Metals: Import build，Metals 不监听文件变更
最容易被忽略的是：Metals 的导入过程本质是启动一个后台 sbt 进程并建立 BSP 连接，它不读你的 IDE 设置，只信任 build.sbt 和你填进 metals.javaHome 的那个 JVM——路径错一点、版本差一级、插件多装一个，都直接表现为 “(connecting)” 卡死，而不是报错提示。
