若VSCode中Scala项目无代码补全等功能，需安装Metals插件、配置Java 11+环境、初始化sbt项目结构、手动导入构建并启用调试支持。
如果您在 Visual Studio Code 中开发 Scala 项目，但无法获得代码补全、跳转定义或实时错误检查等功能，则可能是 Metals 语言服务器未正确配置或未激活。以下是完成 Metals 插件安装、配置与基础使用的具体步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装 Metals 官方插件
Metals 是由 Scala Center 维护的官方语言服务器，需通过 VSCode 扩展市场安装其配套插件，以启用语言功能支持。
1、打开 VSCode，点击左侧活动栏的扩展图标（四个方块组成的图标）。
2、在扩展搜索框中输入 Metals，找到由 scalameta.metals 发布的官方插件。
3、点击“安装”按钮，等待安装完成并重启 VSCode（如提示）。
二、确保系统已安装 Java 11 或更高版本
Metals 依赖 JVM 运行，必须在系统中预装兼容的 Java 运行时环境，否则插件启动将失败并报错“Java home not found”。
1、在终端执行 java -version，确认输出版本号 ≥ 11。
2、若未安装，前往 Adoptium 网站下载并安装 Eclipse Temurin JDK 17（推荐 LTS 版本）。
3、设置环境变量，在 shell 配置文件（如 ~/.zshrc）中添加：export JAVA_HOME=$(/usr/libexec/java_home -v 17)，然后执行 source ~/.zshrc。
三、初始化 Scala 项目结构
Metals 需识别标准的 sbt 或 Mill 构建配置才能加载项目模型；裸 Scala 文件无法触发语言服务。
1、在项目根目录下创建 build.sbt 文件，内容至少包含：ThisBuild / scalaVersion := "3.3.3"。
2、运行 sbt compile 生成 target/ 和 project/ 目录，确保构建能成功执行。
3、在 VSCode 中使用“File → Open Folder”打开该目录，Metals 将自动检测并弹出“Import build?”提示。
四、手动触发构建导入与索引
当自动导入未触发或失败时，可通过命令面板强制启动 Metals 初始化流程，重建符号索引与语义数据库。
1、按下 Cmd + Shift + P（Mac）或 Ctrl + Shift + P（Windows/Linux）打开命令面板。
2、输入并选择 Metals: Import build，等待状态栏显示“Compiling…”及进度条完成。
3、观察底部状态栏右侧是否出现 Metals (ready) 标识，表示语言服务器已就绪。
五、启用调试与测试支持
Metals 内置对 ScalaTest 和 munit 的测试发现与执行能力，需配置 launch.json 才可在编辑器内直接运行单个测试方法。
1、在项目根目录创建 .vscode/launch.json，内容包含 type: "scala" 的配置项。
2、在 Scala 测试文件中右键点击 test 方法名，选择 Debug Test。
3、调试控制台将输出测试日志，断点可在 it("should return true") 行内正常命中。
