Zed 配置 Elm 语言支持：扩展安装、elm-language-server 设置与格式化流程

Zed 并未内置 Elm 支持，而是通过官方扩展体系提供完整的 Elm 开发能力：语法高亮依赖 Tree-sitter，语义级功能（补全、诊断、跳转）由 elm-language-server 提供，格式化与静态检查分别由 elm-format 与 elm-review 完成。本文以 Zed 官方语言文档 docs/src/languages/elm.md 为骨架，结合仓库中 语言服务器配置说明、扩展安装说明 与 语言扩展开发文档，完整讲解如何安装依赖、在 Zed 中开启 Elm 支持，并通过 settings.json 精确控制语言服务器行为与保存时自动格式化。

Elm 在 Zed 中的能力架构

与其他语言一致，Zed 对 Elm 的语言支持建立在两层技术之上（见 configuring-languages.md 开篇说明）：

1. Tree-sitter：负责语法解析与语法高亮，并支撑大纲面板、括号匹配、代码折叠等基于语法树的结构化特性。Elm 使用的语法源自 elm-tooling 维护的 tree-sitter-elm 项目。
2. Language Server Protocol（LSP）：提供补全、诊断、跳转定义、重命名、悬停信息等语义级功能。Elm 使用的语言服务器是 elm-tooling 维护的 elm-language-server。

两者通过 Zed 的扩展机制组织为独立的 Elm 扩展，并不内置于 Zed 主仓库中。Zed 将这种语言支持定义为四类组件：语言元数据与配置（config.toml）、语法（grammar）、Tree-sitter 查询（queries）以及语言服务器（见 extensions/languages.md）。Elm 扩展即按该结构提供上述能力，用户在 Zed 中只需安装扩展即可获得完整的 Elm 语言体验。

Setup：安装扩展与命令行工具

第一步：安装 Elm 扩展

Zed 中的语言扩展需要先安装启用。打开扩展面板（通过快捷键或菜单栏中的 "Extensions"），搜索并安装 Elm 扩展，安装方式与安装目录遵循统一的扩展安装约定（见 installing-extensions.md）：

• macOS：扩展安装于 ~/Library/Application Support/Zed/extensions；
• Linux：位于 $XDG_DATA_HOME/zed/extensions 或 ~/.local/share/zed/extensions；
• Windows：位于 %LOCALAPPDATA%\Zed\extensions。

如需在团队中自动化分发，也可通过 auto_install_extensions 设置在 all-settings.md 中配置自动安装。

第二步：安装语言服务器所需的系统工具

Zed 对 Elm 的支持依赖三个命令行工具，它们负责解析、格式化和静态检查工作，且必须出现在 PATH 环境变量中（或通过 Zed 的 settings 显式指定路径）：

工具	用途	建议安装方式
elm	Elm 编译器，供语言服务器生成诊断	macOS 下 brew install elm，其他平台可参考 Elm 官方安装指南
elm-review	代码静态检查（linting），需以项目依赖形式存在	项目内执行 npm install elm-review --save-dev
elm-format	自动格式化	npm install -g elm-format 全局安装

官方推荐的具体安装命令如下：

# macOS 下安装 elm 编译器
brew install elm

# 在项目目录中安装 elm-review（作为开发依赖，使 .elm 检查可用）
npm install elm-review --save-dev

# 全局安装 elm-format 以支持自动格式化
npm install -g elm-format

其中 elm-review 之所以用 --save-dev 安装到当前项目，是因为它的配置与审查规则通常随项目走；elm-format 则属于编辑器级别的格式化工具，更适合全局安装。若这些可执行文件不在 PATH 中，Zed 的 Elm 支持将无法找到它们，需通过下述语言服务器配置或外置 formatter 的 binary/command 配置显式指定路径。

Configuring elm-language-server：语言服务器配置详解

Elm 语言服务器的初始化选项位于 Zed settings.json 的 lsp 段下。Zed 将 lsp 配置与 languages 配置分离：前者按语言服务器名（此处为 elm-language-server）配置服务器行为，后者按语言名（Elm）配置编辑器级行为。文档给出的配置示例如下：

{
  "lsp": {
    "elm-language-server": {
      "initialization_options": {
        "disableElmLSDiagnostics": true,
        "onlyUpdateDiagnosticsOnSave": false,
        "elmReviewDiagnostics": "warning"
      }
    }
  }
}

这三个初始化选项的语义如下（可依据 elm-language-server 的服务器设置说明与选项命名理解）：

• disableElmLSDiagnostics（布尔值）：是否禁用语言服务器基于 Elm 编译器输出的诊断。示例置为 true，意味着你倾向于依赖 elm-review 等其他来源的诊断，避免重复报错。
• onlyUpdateDiagnosticsOnSave（布尔值）：是否仅在保存文件时更新诊断而非随键入实时刷新。示例为 false，即保持键入时的实时诊断体验。
• elmReviewDiagnostics（字符串）：控制 elm-review 检查结果以何种严重级别呈现。示例中为 "warning"，表示将 elm-review 发现的问题以警告级别展示；可按需调整为其他严重级别或关闭。

注意：这些 initialization_options 属于 LSP initialize 阶段的参数，只在语言服务器启动时发送一次，修改后需要重启语言服务器（如在 Zed 中重新加载窗口或触发语言服务器重启）才能生效。Zed 对语言服务器的配置方式正是采用 LSP 规范中的 initializationOptions（见 configuring-languages.md），并强制要求使用嵌套对象写法而非 VSCode 风格的"点分字符串"（如 "disableElmLSDiagnostics": true 是正确的，而形如 "elmReview.diagnostics": "warning" 的点路径写法不被支持）。

配置存放位置与作用范围

lsp 配置既可以写入全局的用户设置文件（macOS 为 ~/Library/Application Support/Zed/settings.json，Linux 为 ~/.config/zed/settings.json），也可以写入项目内的 .zed/settings.json，后者仅对当前项目生效。Elm 项目常见做法是：将 elm-review 的依赖与规则固定在项目内，同时把 elm-language-server 的初始化选项放进项目级 .zed/settings.json，从而让团队共享同一套诊断行为。

配置 elm-format：实现保存时自动格式化

格式化属于 Zed 中"语言级设置"，通过 languages 段为 Elm 指定外部格式化命令与触发时机。由于文档明确要求安装 elm-format 以支持自动格式化，可结合 Zed 的 formatter 配置机制（详见 configuring-languages.md）在 settings.json 中补充如下配置：

{
  "languages": {
    "Elm": {
      "formatter": {
        "external": {
          "command": "elm-format",
          "arguments": ["--stdin", "--yes"]
        }
      },
      "format_on_save": "on"
    }
  }
}

关键点说明：

• 语言名键：languages 下的键为语言在 Zed 中注册的显示名称。对于扩展提供的语言，该名称取自扩展内 config.toml 的 name 字段（见 extensions/languages.md），Elm 扩展注册的名称即 Elm。
• 外部 formatter：elm-format 从 stdin 读取源码并输出格式化后的结果，因此使用 "external" 结构并传入 --stdin（配合 --yes 跳过交互确认），与 JavaScript 场景下以 Prettier 作外部 formatter 的用法一致。
• format_on_save：设为 "on" 后，每次保存 .elm 文件都会自动执行格式化。若希望手动触发，也可在保存前执行 Zed 的格式化动作。
• 语言级设置会整体替换全局同名设置而非合并，因此如需与其他全局配置共存，请保持结构与键名正确。

格式化与静态检查可以组合：将 elm-format 配置为 formatter、通过语言服务器的 elmReviewDiagnostics 控制检查级别，即可在 Zed 中实现"保存即格式化、实时见检查结果"的 Elm 开发闭环。

故障排查要点

当 Elm 的诊断、格式化或 elm-review 结果不符合预期时，可沿以下思路定位（对应 configuring-languages.md 的通用排查建议）：

1. 确认命令行工具可见：在终端分别执行 which elm、which elm-format、elm-review（项目内）验证可执行文件均位于 PATH。文档明确指出"elm-format、elm-review 和 elm 需要被安装并可在环境中获得，或在 settings 中进行配置"，因此若使用非标准安装位置，需要在对应配置段中为服务器或外部命令显式指定路径。
2. 检查 Zed 日志：通过命令面板打开 Zed 日志（命令面板中搜索 Open Log），查看语言服务器启动或格式化调用阶段的报错信息。
3. 确认扩展已安装且配置已生效：在 Zed 中打开任意 .elm 文件，观察语言服务器是否成功连接；修改 initialization_options 后记得重启语言服务器。
4. 区分诊断来源：Elm 语言的诊断可能来自编译器（受 disableElmLSDiagnostics 影响）与 elm-review（受 elmReviewDiagnostics 影响）两条通道，调整选项前先判断报错实际来自哪一方，避免误关错通道。

相关文档导航

如需进一步深入，可继续阅读仓库内以下文档：

• Elm 语言支持原始文档：本文的骨架来源，含官方配置示例的完整版本。
• 语言服务器与 Tree-sitter 配置：lsp 段、嵌套初始化选项、外部 formatter 与 format_on_save 的通用机制。
• 安装扩展：扩展安装目录与自动安装说明。
• 语言扩展开发：语言扩展中 config.toml、grammar 与 Tree-sitter queries 的组织方式。
• 全部设置参考：languages、lsp、auto_install_extensions 等完整设置项说明。
• 支持的语言总览：查看其他基于扩展的语言支持情况。