必须配置metals.javaHome路径、创建build.sbt文件并手动执行Metals: Import build，三者缺一不可；还需禁用其他Scala插件、确保语言模式为“Scala (Metals)”，否则将卡在启动状态或功能异常。
装完 Metals 插件不等于能写 Scala——缺 metals.javaHome、没 build.sbt、不手动执行 Metals: Import build，三者任一缺失都会卡在 “Starting Metals…” 或状态栏一直显示 “(connecting)”。
Java 17 路径必须显式填进 settings.json
VSCode 不读 JAVA_HOME，也不自动扫描 JDK 安装目录。哪怕终端里 java -version 输出是 17.0.2，VSCode 仍可能用错 JVM。
- 先确认真实路径：
/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 等插件后，跳转失效、补全卡顿、右键菜单消失——它们不会报错，只会悄悄抢资源、干扰 BSP 连接。
- 打开 VSCode 扩展面板，搜索
scala - 把除
scalameta.metals外所有插件全部禁用 - 确认
.scala文件右下角语言模式是Scala (Metals)，不是Scala或Plain Text - 如果已导入但符号跳转仍失效，大概率是上一步漏禁用了某个插件
最容易被忽略的是：导入成功后右下角显示 Metals (ready)，但如果你打不开 build.sbt 修改后没再执行一次 Metals: Import build，所有新声明的依赖、模块或编译选项都不会生效——Metals 不监听文件变更，只认你手动触发的那一次导入。
