在 Zed 中配置 Scala 开发环境：Metals 语言服务器与 Almond REPL 完整指南

本指南介绍在 Zed（本项目 Zed 编辑器，docs/src/languages/scala.md）中为 Scala 配置完整开发体验的方法。Scala 支持并非 Zed 内置，而是由社区维护的 Scala 扩展（基于 Metals 语言服务器与 tree-sitter 语法解析器）提供。阅读完本文后，你将掌握：如何从零搭建 JDK/Scala 工具链与 Almond REPL、如何在 Zed 中安装并启用 Scala 扩展、如何通过 .scalafmt.conf 与 .scalafix.conf 控制格式化与静态检查行为，以及如何在编辑器里以类似 Jupyter 的方式交互式运行 Scala 代码。

Scala 语言支持在 Zed 中的实现方式

与多数"开箱即用"的语言不同，Zed 的 Scala 支持由社区维护的扩展提供，其官方入口与依赖组件如下（详见 docs/src/languages/scala.md）：

• Zed Scala 扩展：由 scalameta 社区维护的 metals-zed，提供 Zed 侧的 Scala 能力接入，问题请上报到该扩展的 issues 页面；
• 语法解析（Tree-sitter）：采用 tree-sitter-scala 为 Scala/Scala 3 源码提供语法树、高亮、折叠与大纲等基础编辑能力；
• 语言服务器（Language Server）：采用 Metals（scalameta/metals），提供补全、跳转、重命名、类型错误诊断、格式化与导入整理等"智能"功能。

从仓库目录结构可以印证这一"内置语言在 extensions/、其余靠扩展"的组织方式：Zed 在 docs/src/languages.md 中明确区分了"开箱即用"的语言与"依赖第三方扩展"的语言，Scala 属于后者，并在该文件的社区扩展列表中登记为 Metals 扩展；同时本仓库自带的 extensions 目录只包含 glsl、html、proto 等少量内置扩展，并不包含 Scala，说明 Scala 代码解析与 LSP 均由安装扩展后提供。

Zed 安装扩展的统一方式参见 安装扩展文档：打开命令面板执行 zed::Extensions（或菜单栏 Zed > Extensions）进入扩展画廊，搜索 Scala 或 Metals 并安装；安装后扩展源码位于 Zed 的数据目录（Linux 为 $XDG_DATA_HOME/zed/extensions/installed 或 ~/.local/share/zed/extensions/installed），扩展自行下载的语言服务器等文件则写入其 work 子目录。若希望自动化安装，可参考 auto_install_extensions 设置项。

搭建前置工具链：JDK 与 Scala（cs setup）

Metals 运行在 JVM 之上，因此需要先准备 JDK 与 Scala 构建工具链。Zed 的官方 Scala 文档给出如下安装路径：

1. 安装 OpenJDK（macOS 使用 Homebrew，来自 Eclipse 基金会官方 OpenJDK 二进制）：

   brew install --cask temurin
   

   这是 Almond REPL（后续章节）与 Metals 都依赖的运行时，务必优先完成。其他平台请使用与官方发布对应的安装方式安装 Temurin/OpenJDK 17+。

2. 安装 Coursier 并执行 cs setup，一步到位完成 Scala 发行版、sbt、scala-cli 等默认工具链的引导：

   brew install coursier/formulas/coursier && cs setup
   

   cs setup 是 Coursier 提供的引导命令：它会将 coursier 加入 PATH、下载并配置默认的 Scala 版本与构建工具，并写入相应的环境变量（如 JAVA_HOME 相关配置），是官方推荐的 Scala 快速安装方式。上述命令基于 macOS 的 Homebrew 写法；在 Linux/Windows 上，请改用 Coursier 官方发布的安装脚本或包管理器先安装 cs，再执行 cs setup。

安装完成后，可在终端执行 cs launch scala 或 scala -version 验证工具链是否就绪。若后续在 Zed 中打开 Scala 项目时 Metals 报"找不到 JDK/build tool"类错误，通常意味着本步骤未正确完成或 PATH 未被 Zed 会话继承。

在 Zed 中启用 Scala 并让 Metals 接管项目

工具链就绪后，安装上文提到的 Scala（Metals）扩展，然后：

1. 重启或重载 Zed，打开任意 Scala 项目（包含 build.sbt、*.scala 或 *.sc 文件）；
2. 扩展会检测项目类型并尝试启动 Metals。首次启动时 Metals 需要下载依赖、编译构建定义（如 sbt 的 project 层），耗时较长属正常现象；
3. 状态栏出现 Metals 相关提示后，即可获得补全、悬停、跳转定义、引用查找、重构与导入整理等语言服务器能力，文件顶部语法高亮与大纲由 tree-sitter 解析器驱动。

Zed 中语言服务器二进制、启动参数等可通过各语言扩展内部声明，并在 配置语言服务器的通用设置 中查看如何在 settings.json 的 "lsp" 段对特定语言服务器进行参数追加或二进制覆盖。需要特别说明的是：本仓库的 Scala 文档在源码中留有一处 TODO 注释，注明"为 Zed 的 settings.json 提供 metals LSP 配置示例（如 metals.javaHome、metals.excludedPackages、metals.customProjectRoot 等）"，即这些 Metals 初始化选项当前仍需以 Metals 侧的用户配置方式提供，读者不必在 Zed 的 settings.json 中手工设置。

控制 Metals 行为：.scalafmt.conf 与 .scalafix.conf

Metals 语言服务器的"行为"（即格式化风格、静态检查规则）并非由 Zed 配置直接控制，而是通过 Scala 生态的标准配置文件驱动：

配置文件	作用	说明
.scalafmt.conf	格式化（Scalafmt）	控制缩进、换行、导入排序等代码风格
.scalafix.conf	静态检查/自动修复（Scalafix）	声明需要运行的规则（如导入整理、废弃语法迁移）

你可以把这两个文件放在项目根目录，也可以显式指定其位置（通过 Metals 的用户配置）。Metals 会自动探测项目根目录下的这些文件并据此格式化/检查代码。

• 关于 Scalafix 配置（规则写法、启用方式等）参见 Scalafix 官方配置文档；
• 关于 Scalafmt 配置（version、runner.dialect、maxColumn 等全部参数）参见 Scalafmt 官方配置文档；
• 有关如何在 Metals 侧指定这些文件的位置及更多用户级配置（如 javaHome、excludedPackages、customProjectRoot），参见 Metals 的用户配置文档。

Zed 中触发格式化的方式与其它语言一致：保存时自动格式化或执行格式化命令。一个示意性的 .scalafmt.conf 片段形如：

version = 3.8.3
runner.dialect = scala3
maxColumn = 100

上述字段仅为示意，version 必须与所用 Scalafmt 发布版本对应；实际字段请以上述官方配置文档为准（其内容是 Scala 生态工具的标准契约，独立于本仓库）。

当你想让某个项目使用与全局不同的格式化风格，或为不同模块指定不同的规则集时，只需在各项目根目录放置各自的配置文件——Metals 会按打开文件所属项目自动选用。

在 Zed 中交互式运行 Scala：安装 Almond 内核

除了静态开发，Zed 还内置了一套基于 Jupyter 内核的 REPL 机制（完整说明见 Zed REPL 文档），Scala 是其中官方支持的语言之一，对应的内核为 Almond。你可以在普通编辑器文件中选中代码、以单元格方式运行并立即看到输出。

安装 Almond 内核

按官方快速安装步骤，在 JDK + Coursier 就绪后执行：

brew install --cask temurin                 # 安装 OpenJDK（Eclipse 基金会官方二进制）
brew install coursier/formulas/coursier && cs setup
coursier launch --use-bootstrap almond -- --install

第三条命令通过 coursier launch 以 bootstrap 方式启动 Almond 并调用 --install，将其注册为 Jupyter kernelspec（默认注册为 scala 内核）。完成后可用 jupyter kernelspec list 验证（需本机装有 jupyter），输出中应能看到名为 scala（或 almond）的条目及其安装路径。

在 Zed 中运行 Scala 代码

1. 安装内核后，若 Zed 已打开，执行 repl::RefreshKernelspecs 命令刷新内核列表，使新内核可用（见 REPL 文档）；
2. 打开一个 .scala（或支持内嵌 Scala 的 Markdown 代码块），执行 repl::Run（macOS 默认快捷键为 ctrl-shift-enter），Zed 会对当前选区/行/单元格执行并在下方显示运行结果；
3. 输出可通过 repl::ClearOutputs 命令或工具栏的 REPL 菜单清空；
4. Zed 自动探测可用内核并分类组织在内核选择器中（推荐内核、语言匹配的 Jupyter kernelspec、远程服务器等）；可在 settings.json 的 jupyter.kernel_selections 中为语言指定默认内核。参考 REPL 文档 给出的模板，为 Scala 固定使用 Almond 可写成：

{
  "jupyter": {
    "kernel_selections": {
      "scala": "almond"
    }
  }
}

上例中 "almond" 需与实际 jupyter kernelspec list 显示的内核名一致，请以本机注册的内核名为准。

调试内核问题

• 用 repl::Sessions 查看当前可用内核会话；repl::RefreshKernelspecs 用于重新扫描新安装的内核；
• 本机装有 jupyter 时，直接在终端执行 jupyter kernelspec list 可核对 Almond 是否注册成功及其路径；
• 若执行代码无反应，优先排查 JDK 是否可被 Zed 启动的进程找到（Almond 运行在 JVM 上），并确认 cs setup 阶段写入的环境变量对终端与 Zed 均生效。

常见问题速查

症状	可能原因与处理
打开 Scala 文件无高亮/大纲	Scala 扩展未安装，执行 zed::Extensions 安装 Scala（Metals）扩展
Metals 无法启动或反复下载依赖	缺少 JDK，先完成 brew install --cask temurin；确认 cs setup 成功且 PATH 正确
格式化不生效或风格不符预期	检查项目根目录是否存在 .scalafmt.conf，以及文件内 version/runner.dialect 是否与项目 Scala 版本匹配
静态检查/导入整理不执行	项目根目录缺少 .scalafmt.conf 之外的 .scalafix.conf，或规则名书写有误（参见 Scalafix 配置文档）
REPL 无法执行 Scala	Almond 内核未安装或未刷新，重跑 coursier launch --use-bootstrap almond -- --install，再执行 repl::RefreshKernelspecs
希望不同项目使用不同格式化风格	在每个项目根目录分别放置 .scalafmt.conf / .scalafix.conf，Metals 按打开文件所属项目自动选择

进一步阅读

• Scala 语言支持文档：本指南对应的原始文档（含扩展与工具链入口）
• 语言支持总览：Scala 与其它依赖社区扩展的语言清单
• Zed REPL（Jupyter 内核）：REPL 通用用法、内核选择与排障
• 安装扩展：扩展画廊与安装目录说明
• 配置语言服务器：settings.json 中 "lsp" 段的通用配置方式

提示：Scala 与 Metals 的相关工具（scalafmt、scalafix、Almond）属于 Scala 生态的持续演进组件，具体配置参数请以对应工具官方文档为准；本仓库 Scala 文档中提到的 metals 初始化参数（javaHome、excludedPackages、customProjectRoot 等）属 Metals 用户配置范畴，可在其用户配置文档中查阅。