第128章 Zed 扩展开发指南

Zed 扩展是包含 extension.toml 清单文件的 Git 仓库，可以提供语言、主题、调试器、代码片段和 MCP 服务器等功能。

扩展功能 {#extension-features}

扩展可以提供：

• 语言
• 调试器
• 主题
• 图标主题
• 代码片段
• MCP 服务器

本地开发扩展

在开始为 Zed 开发扩展之前，请先通过 rustup 安装 Rust。

Zed 使用 wasm32-wasip2 Rust target 来编译扩展。如果 Rust 是通过 rustup 安装的，Zed 会自动安装该 target；如果是通过其他方式安装的（如 Homebrew 或 Nix），则需要自行提供 wasm32-wasip2 target——例如将其添加到 Nix rust-overlay 或 fenix 工具链的 targets 中。

提供语法的扩展还需要安装 wasi-sdk 来编译 Tree-sitter 解析器。Zed 会自动下载，但你也可以把 WASI_SDK_PATH 环境变量指向已有的安装目录（即包含 bin/clang 的那个目录）。

开发扩展时，无需发布即可在 Zed 中使用，只需将其安装为开发扩展（dev extension）。

在扩展页面点击 Install Dev Extension 按钮（或使用 {#action zed::InstallDevExtension} 操作），然后选择扩展所在的目录即可。

如果需要排查问题，可以查看 Zed.log（{#action zed::OpenLog}）获取更多输出。如需调试日志，先关闭 Zed，再从命令行以 zed --foreground 启动，这样可以看到更详细的 INFO 级日志。

如果你已经安装了该扩展的已发布版本，在开发版安装前，已发布版本将被卸载。安装成功后，Extensions 页面将显示上游扩展状态为“被开发版扩展覆盖”。

Zed 扩展的目录结构

Zed 扩展是一个 Git 仓库，其中包含 extension.toml 文件。该文件必须包含关于扩展的一些基本信息：

id = "my-extension"
name = "My extension"
version = "0.0.1"
schema_version = 1
authors = ["Your Name <you@example.com>"]
description = "Example extension"
repository = "https://github.com/your-name/my-zed-extension"

除了上述文件，还有若干可选的文件和目录可用于为 Zed 扩展添加功能。一个具备完整功能的扩展示例目录结构如下：

my-extension/
  extension.toml
  Cargo.toml
  src/
    lib.rs
  languages/
    my-language/
      config.toml
      highlights.scm
  themes/
    my-theme.json
  snippets/
    snippets.json
    rust.json

Rust 和 WebAssembly

请注意，大多数扩展即使没有 Rust 代码也能正常工作。具体而言，只有 language server、context server 和 debugger 扩展需要自定义 Rust 代码才能正常运行。

扩展的过程化部分使用 Rust 编写并编译为 WebAssembly。若要开发包含自定义代码的扩展，请包含如下的 Cargo.toml：

[package]
name = "my-extension"
version = "0.0.1"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
zed_extension_api = "0.1.0"

请从 crates.io 使用最新版本的 zed_extension_api。请确保其与你想要支持的 Zed 版本兼容。

在 Rust crate 的 src/lib.rs 文件中，你需要为扩展定义一个 struct 并实现 Extension trait，同时使用 register_extension! 宏注册该扩展：

use zed_extension_api as zed;

struct MyExtension {
    // ... state
}

impl zed::Extension for MyExtension {
    // ...
}

zed::register_extension!(MyExtension);

由于扩展会被编译为 WebAssembly，部分 Rust 特性可能不符合预期。例如，cfg 指令无效，且 std::env::var 也不会返回预期结果。请改用 zed_extension_api::current_platform 方法获取当前环境信息，并熟悉用于读取环境变量及在用户 PATH 中查找可执行文件的 Worktree struct 及其方法。

调试你的 Rust 扩展

stdout/stderr 会直接转发给 Zed 进程。若要查看扩展中 println!/dbg! 的输出，可在终端中添加 --foreground 参数启动 Zed。