开发扩展

扩展功能

扩展可以为 Zed 添加以下功能

本地开发扩展

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

Rust 必须通过 rustup 安装。如果您通过 homebrew 或其他方式安装了 Rust，则无法安装开发扩展。

开发扩展时，您无需发布即可在 Zed 中使用它，只需将其安装为开发扩展即可。

从扩展页面，单击安装开发扩展按钮（或zed: install dev extension操作），然后选择包含您的扩展的目录。

如果您需要进行故障排除，可以查看 Zed.log (zed: open log) 以获取更多输出。对于调试输出，请从命令行关闭并重新启动 Zed，并使用zed --foreground，这将显示更详细的 INFO 级别日志记录。

如果您已安装扩展的已发布版本，则在安装开发扩展之前会卸载已发布版本。成功安装后，扩展页面将指示上游扩展“被开发扩展覆盖”。

Zed 扩展的目录结构

Zed 扩展是一个包含extension.toml的 Git 仓库。此文件必须包含有关扩展的一些基本信息

id = "my-extension"
name = "My extension"
version = "0.0.1"
schema_version = 1
authors = ["Your Name <you@example.com>"]
description = "My cool 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

WebAssembly

扩展的程序部分用 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文件中，您需要为扩展定义一个结构体并实现Extension trait，并使用register_extension!宏注册您的扩展

use zed_extension_api as zed;

struct MyExtension {
    // ... state
}

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

zed::register_extension!(MyExtension);

stdout/stderr直接转发到 Zed 进程。为了查看扩展的println!/dbg!输出，您可以在终端中启动 Zed，并带有--foreground标志。

Fork 和克隆仓库

Fork 仓库

注意：如果您将zed-industries/extensions仓库 Fork 到个人 GitHub 帐户而不是 GitHub 组织，这将非常有帮助，因为这允许 Zed 员工将任何所需的更改推送到您的 PR，以加快发布过程。

将仓库克隆到您的本地机器

# Substitute the url of your fork here:
# git clone https://github.com/zed-industries/extensions
cd extensions
git submodule init
git submodule update

扩展许可证要求

截至 2025 年 10 月 1 日，扩展仓库必须包含许可证。接受以下许可证

这允许我们将从您的扩展代码生成的二进制文件分发给我们的用户。如果没有有效的许可证，在后续步骤中添加或更新您的扩展的拉取请求将无法通过 CI。

您的许可证文件应位于扩展仓库的根目录。任何以LICENCE或LICENSE为前缀的文件名（不区分大小写）都将进行检查，以确保它与其中一个接受的许可证匹配。请参阅许可证验证源代码。

此许可证要求仅适用于您的扩展代码本身（编译成扩展二进制文件的代码）。它不适用于您的扩展可能下载或与之交互的任何工具，例如语言服务器或其他外部依赖项。如果您的仓库同时包含扩展代码和其他项目（如语言服务器），则您无需重新许可这些其他项目——只有扩展代码需要是上述接受的许可证之一。

发布您的扩展

要发布扩展，请向zed-industries/extensions仓库打开 PR。

在您的 PR 中，执行以下操作

将您的扩展添加为extensions/目录中的 Git 子模块

git submodule add https://github.com/your-username/foobar-zed.git extensions/foobar
git add extensions/foobar

所有扩展子模块都必须使用 HTTPS URL 而不是 SSH URL (git@github.com)。

在顶级extensions.toml文件中添加包含您的扩展的新条目

[my-extension]
submodule = "extensions/my-extension"
version = "0.0.1"

如果您的扩展位于子模块内的子目录中，您可以使用path字段指向扩展所在的位置。

运行pnpm sort-extensions以确保extensions.toml和.gitmodules已排序

您的 PR 合并后，扩展将打包并发布到 Zed 扩展注册表。

扩展 ID 和名称不应包含zed或Zed，因为它们都是 Zed 扩展。

更新扩展

要更新扩展，请向zed-industries/extensions仓库打开 PR。

在您的 PR 中执行以下操作

将扩展的子模块更新到新版本的提交。
更新extensions.toml中扩展的version字段
- 确保version与特定提交中extension.toml中设置的版本匹配。

如果您想自动化此过程，可以使用社区 GitHub Action。

注意：如果您的扩展仓库具有不同的许可证，您需要先将其更新为接受的扩展许可证之一，然后才能发布您的更新。