VSCode 运行 Scala 的关键在于 Metals 成功连接 sbt 构建服务器；需确保 JDK 11–17、sbt 版本与项目匹配，正确配置 JAVA_HOME 和 metals.javaHome，修改 build.sbt 后手动执行 Metals: Import build，Spark 调试须用 local[*] 模式，Scala 3 项目需显式声明 scalaVersion 并清理缓存。
VSCode 能跑 Scala，但不是装完插件就“能用”，关键在 Metals 是否真正连上 sbt 构建服务器——卡在 Importing build 或状态栏没出现 Metals: Ready，90% 是构建工具链没对齐，不是 VSCode 本身的问题。
Java 和 sbt 版本必须匹配 Metals 的预期
Metals 内部依赖 sbt 启动构建服务器（BSP），而 sbt 又强依赖 JDK 版本。JDK 21 虽新，但当前 Metals（截至 2026 年 4 月）稳定支持的仍是 JDK 11–17。sbt 也一样：项目若锁定了 sbt.version=1.9.9（常见于 Spark 3.5+ 项目），你本地装了 sbt 2.x 就会静默失败。
- 检查方式：打开终端，运行
sbt --version和java -version，确认二者都在 Metals 兼容范围内 - 项目级锁定看
project/build.properties，不是build.sbt - Windows 用户尤其注意：
JAVA_HOME必须指向 JDK 根目录（如C:\Program Files\Java\jdk-17），不能是jre子目录，也不能带尾部反斜杠 - VSCode 设置里显式填
metals.javaHome，比依赖系统环境变量更可靠
build.sbt 改了，代码没提示？别急着重装插件
Metals 不会实时监听 build.sbt 变更，它只在导入时做一次静态解析。改了依赖、Scala 版本或插件后，补全失效、跳转报错，不是插件坏了，是语义索引没更新。
- 保存
build.sbt后，按Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入并执行Metals: Import build - 如果卡住，先关掉 VSCode，删掉项目根目录下的
.metals/和target/，再重开并手动触发导入 - 避免在
build.sbt里写动态逻辑（比如sys.process调外部命令、读文件生成版本号），Metals 解析器不执行代码，这类写法会被跳过，导致模块识别失败
调试 Spark 项目时断点不生效？大概率是启动模式错了
Spark 本地调试和普通 Scala 应用完全不同。VSCode 的 launch.json 调试器 attach 的是主 JVM 进程，而 spark-submit 会 fork 新进程，断点自然失效。
- 必须用
local[*]模式：确保build.sbt或代码中显式设置spark.master = "local[*]" - 不要用
spark-submit命令运行——改用 VSCode 右键菜单里的Run this file with Metals，或配置launch.json中的mainClass直接启动 Driver - 注意
provided依赖：Spark 的spark-sql_2.12等在本地调试时不会被加载，若代码里用了未声明为compile的 Spark API，会直接NoClassDefFoundError - UI 端口冲突常见于反复调试：加
--conf spark.ui.port=4041避免默认 4040 占用
最易忽略的一点：Metals 对 Scala 3 项目默认可能降级为 Scala 2 模式解析，尤其当你用 sbt new scala/hello-world.g8 创建模板时。首次打开后若发现类型推导异常或 given 关键字无提示，别调设置，先删 .metals/ 和 target/，再重开并确认 build.sbt 里写了 scalaVersion := "3.3.1"（或更高稳定版）。
