VSCode运行Scala代码需Metals语言服务器+构建上下文，而非仅插件或命令；必须满足JDK 17、sbt≥1.9.0、build.sbt明确指定scalaVersion，否则右键运行失败、导入卡住或断点无效。

scalac 和 scala 命令能跑 ≠ VSCode 能运行 Scala 代码。真正起作用的是 Metals 语言服务器 + 正确的构建上下文，不是语法高亮插件或手动敲命令。

为什么装了插件还运行不了？

常见现象：点右键“Run this file with Metals”没反应、终端报 No main class found、状态栏卡在 Importing build...。根本原因不是插件没装，而是缺失三个硬性前提：

• JDK 17（不是 8、11、21）必须已安装且 java -version 输出含 17.0.
• sbt ≥ 1.9.0 必须可用，sbt --version 要有输出；scala 命令已弃用，别依赖它
• 项目根目录必须有 build.sbt，且其中明确写了 ThisBuild / scalaVersion := "3.3.3" —— 写成 "3" 或留空，Metals 直接拒绝解析

运行单个 .scala 文件的实操路径

VSCode 不支持像 Python 那样直接“右键运行裸文件”。必须让 Metals 把它识别为可执行模块：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 确保该文件里定义的是 object，且含 def main(args: Array[String]): Unit 方法（不能是 class 或 trait）
• 文件名要和 object 名一致，比如 App.scala 里写 object App
• 右键文件 → 选 Run this file with Metals，它会自动推导 mainClass 并启动 JVM
• 若失败，看 VSCode 底部状态栏是否显示 Metals (ready)；没显示就先执行 Metals: Import build

调试时 launch.json 配置的关键陷阱

纯运行靠右键，但断点调试必须配 .vscode/launch.json。最容易错的不是语法，而是语义绑定：

• mainClass 值必须是完整包路径 + object 名，比如 com.example.HelloWorld，不能只写 HelloWorld
• 如果项目用了 provided 依赖（如 Spark），本地调试时这些类默认不进 classpath —— 必须在 build.sbt 中临时改成 compile 范围，否则断点一进 spark.read 就抛 NoClassDefFoundError
• type: "scala" 是固定值，别写成 java 或 jvm；VSCode 旧版插件可能不识别，确认 Metals 扩展版本 ≥ 0.11.12

build.sbt 改了但运行/补全不更新？

Metals 不监听文件变更，改完 build.sbt 后不会自动重载索引。这是最常被忽略的同步动作：

• 保存 build.sbt 后，必须手动触发 Metals: Import build（Cmd+Shift+P / Ctrl+Shift+P）
• 如果导入卡住，不要反复点“Reload Window”，先删掉项目根目录下的 .metals/ 和 target/，再重试
• 多模块项目中，某个子模块没设 scalaVersion，Metals 会跳过它 —— 每个 project 块里都要显式声明

Metals 的“运行”本质是启动一个受控的 sbt 子进程并 attach 调试器，不是调 shell 执行 scala *.scala。所有行为都绕不开构建定义和 JVM 兼容性，版本错一位，整个链路就断。