在 Zed 中启用 Luau 支持：社区扩展、luau-lsp 语言服务与 StyLua 格式化配置实战

Zed 通过社区维护的 Luau 扩展为 Luau（Roblox 开发的、源自 Lua 的快速、小巧、安全、渐进类型化的嵌入式脚本语言）提供语法高亮、语言服务器与格式化支持。读完本文，你将掌握在 Zed 中安装 Luau 扩展、接线 luau-lsp 能力，以及使用 StyLua 配置"保存即格式化"的完整方法，并能依据仓库源码理解其底层落地细节。

Luau 语言与 Zed 的支持形态

Luau 由 Roblox 基于 Lua 5.1 演化而来，保持小巧、可嵌入特性的同时引入了类型推断与类型语法，并被 Roblox 生态大规模使用，以 MIT 协议开源。在 Zed 中，Luau 与 Lua 是两条独立语言通道：

• Lua：由 Lua 扩展 提供，文档见 Lua，默认走 LuaLS / lua-language-server。
• Luau：由社区维护的 Luau 扩展（4teapo/zed-luau）提供，核心组件为 Tree-sitter 语法解析器 4teapo/tree-sitter-luau 与语言服务器 JohnnyMorganz/luau-lsp。

值得注意的是，Zed 仓库本身并没有把 Luau 语法内置为一级语言，而是遵循"核心编辑器 + 第三方扩展"的语言接入范式。这一判断在 docs/src/languages.md 的语言索引中可以得到印证：Luau 与 Lua 均以文档条目形式出现但未标注内建星号 *，与 Bash、C、Rust 等编译进内核的语言区分开来。

安装并启用 Luau 扩展

在 Zed 中安装 Luau 扩展的路径与安装其他语言扩展一致，详见 安装扩展：

1. 打开扩展面板，搜索 Luau（社区维护者 4teapo 发布的 zed-luau）；
2. 点击安装并启用，随后即可获得针对 .luau 文件的识别与基础语法能力；
3. 由于 Luau 扩展负责的是语言感知部分，工程化能力（补全、诊断）由 luau-lsp 按需驱动；格式化则默认外接 StyLua，三者互相解耦。

Zed 在安装后如何感知 Luau 文件？从仓库源码可看到两条直接证据：

• 文件类型注册与图标绑定：在 crates/theme/src/icon_theme.rs 中注册了 ("luau", &["luau"]) 的文件类型映射，并在同文件 L363 将 luau 类型关联到 icons/file_icons/luau.svg——对应图标资源真实存在于 assets/icons/file_icons/luau.svg，这意味着以 .luau 结尾的文件一旦被识别，侧边栏与标签页即会显示专属图标。
• luaurc 作为 JSONC 解析：在 crates/grammars/src/jsonc/config.toml 的 path_suffixes 中，luaurc 与 tsconfig.json、pyrightconfig.json 等并列，说明 Luau/Roblox 工程常见的 luaurc 配置文件在 Zed 中会被当作带注释的 JSON（JSONC）高亮与校验，配置注释不会被误报语法错误。

语言服务器与工程配置

文档明确提示，完整的 Luau 扩展配置说明以扩展自带的 README 为准，本文从仓库侧补充可验证的落地要点：

• luau-lsp 负责类型诊断：luau-lsp 会读取 Roblox/Luau 工程的 luaurc 文件来获得类型库、别名与编译开关。Zed 侧无需手写 LSP 启动参数，扩展安装后即接管语言服务生命周期，你只需确保工程根的 luaurc 配置正确即可（该文件已被识别为 JSONC，支持注释，可放心编写）。
• 语言级设置入口：Zed 允许按语言覆盖行为。在 Settings（命令面板执行 zed: Open Settings 打开的 settings 文件，或图形化设置界面 Languages > Luau 节点）中，以 languages.Luau 为键配置。语言级设置机制与 Lua、JavaScript 等语言一致，可同时设置 formatter、format_on_save 等项，通用规则参见 配置语言支持。

使用 StyLua 实现自动格式化

Luau 在 Zed 中没有内建格式化器，官方推荐接入 StyLua——JohnnyMorganz 出品的 Lua/Luau 代码格式化器，二者作者同源，对 Luau 语法支持最为完整。

第一步：安装 StyLua

按平台二选一即可：

# macOS 通过 Homebrew
brew install stylua

# 或通过 Cargo 源码安装（按需裁剪不需要的语法特性）
cargo install stylua --features lua52,lua53,lua54,luau

注意 Cargo 安装方式中 --features 决定 StyLua 编译时支持的语言变体：如果只写 Luau 代码，可精简为 cargo install stylua --features luau；同时处理 Lua 5.2–5.4 与 Luau 工程时再保留全部特性。同理的裁剪思路也可在 Lua 语言文档 的 StyLua 一节对照参考。

第二步：在 settings 中配置 Luau 外部格式化器

Zed 的 formatter.external 会调用外部命令，通过标准输入（stdin）接收缓冲区全文、从标准输出读取格式化结果。为 Luau 添加如下配置：

{
  "languages": {
    "Luau": {
      "formatter": {
        "external": {
          "command": "stylua",
          "arguments": ["-"]
        }
      }
    }
  }
}

其中：

• command: "stylua"：要求 stylua 已加入 PATH；
• arguments: ["-"]：- 让 StyLua 从 stdin 读取源码并写回 stdout，恰好匹配 Zed 外部格式化器的管道协议。

若想格式化时显式指定语法风格，可参照 Lua 文档 中更完整的参数形态，把参数扩展为 --syntax=Luau、--respect-ignores 以及保留原路径信息的 --stdin-filepath/{buffer_path}。{buffer_path} 是 Zed 提供给外部命令的内置占位变量，会展开为当前文件路径，使 StyLua 能读取项目内 stylua.toml 的忽略规则——该变量同样被 配置语言支持 的 Prettier 示例使用，是通用的外部命令能力。

第三步：开启保存时格式化（可选）

在语言配置同级追加 format_on_save，即可把格式化时机绑定到每次保存：

{
  "languages": {
    "Luau": {
      "format_on_save": "on",
      "formatter": {
        "external": {
          "command": "stylua",
          "arguments": ["-"]
        }
      }
    }
  }
}

format_on_save 同样可用 "off" 关闭；此外 Zed 还支持 format_on_paste 等语言级开关。需要提醒的是，按 配置语言支持 的说明，外部命令格式化器不支持选区范围格式化，因此对 Luau 使用 zed: Format Selection 之类范围格式化操作时会被跳过——这是外部管道式格式化器的通用约束，而非缺陷。

工程级风格：项目内 stylua.toml

上述 settings 只解决"谁来格式化"，风格统一建议交给项目内的 stylua.toml。Zed 调用 stylua - 时，StyLua 会向上查找项目根的配置文件自动生效。可参照以下模板（语法取值需将默认的 Lua 变体显式指定为 Luau，才能正确识别 Luau 专属语法）：

syntax = "Luau"
column_width = 120
line_endings = "Unix"
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferDouble"
call_parentheses = "Always"
collapse_simple_statement = "All"

[sort_requires]
enabled = true

这种"编辑器无关、配置文件入仓库"的做法能保证团队成员共享同一套 Luau 排版规范，stylua.toml 中 syntax = "Luau" 与第二步 --syntax=Luau 命令行取值含义一致，二者只需保留其一（文件配置优先级更高）。

验证配置是否生效

完成以上步骤后，可以按顺序做最小验证：

1. 打开一个 .luau 文件，确认侧边栏/标签页出现 Luau 图标（佐证见 assets/icons/file_icons/luau.svg），语法高亮正常；
2. 输入一段能触发类型推断的代码，观察 luau-lsp 是否给出补全与诊断（依赖扩展与 luaurc 的接线是否正确）；
3. 故意把缩进与引号写乱，执行保存或 zed: Format，观察代码是否被 StyLua 重排；
4. 若格式化无反应，优先排查：stylua 是否在 PATH 中、settings 中语言键是否精确写作 "Luau"（大小写需与 Zed 内部语言名一致）、是否误将 Luau 配置写进了 Lua 节点下。

小结

Luau 在 Zed 中的支持链条清晰解耦：扩展提供语言感知，luau-lsp 提供类型级智能，StyLua 提供格式化。配置的核心动作只有两处——安装 Luau 扩展、在 languages.Luau 节点挂载 stylua 外部格式化器，配合工程内 stylua.toml 即可获得与 Lua 同样顺滑、且更贴合 Roblox/Luau 工程实践的编辑体验。相关语言支持清单见 docs/src/languages.md，格式化通用机制见 配置语言支持。