Zed 扩展发布指南：从 PR 提交到进入 Zed 扩展仓库的完整流程

2026-09-06 18:10:00作者：傅爽业Veleda

导读

本文聚焦 Zed 扩展的发布（Publishing）流程——即如何把你在本地开发完成的 Zed 扩展，通过提交 Pull Request 的方式合入官方扩展仓库，并最终被打包、发布到 Zed 扩展仓库、供全球用户安装使用。文中将完整覆盖发布前置条件、许可证要求、PR 提交规则、Git 子模块接线方法、extensions.toml 配置字段、审查流程，以及发布后的更新与维护策略，帮助你走通「开发 → 提交 → 审查 → 发布 → 迭代」的完整生命周期。

在动手提交之前，请先通读本节引用的发布前置条件与许可证要求，并逐条确认你的扩展已满足全部要求。只有满足这些要求后再进入下方步骤，否则发布可能被延迟，甚至被直接拒绝。

一次发布涉及的三个角色

理解 Zed 扩展的发布机制，先要厘清三者的关系：

扩展开发者：编写扩展代码，并将代码仓库托管在公开 Git 托管平台上；
Zed 扩展仓库（zed-industries/extensions）：Zed 官方维护的聚合仓库，本身并不存放扩展源码，而是通过 Git 子模块指向各个扩展各自的仓库，并维护一份顶层 extensions.toml 清单；
Zed 扩展仓库本体：扩展被正式收录后，由官方 CI 完成打包并发布到 Zed 扩展仓库，用户即可在 Zed 中搜索、安装。

也就是说，你并不需要把扩展源码「上传」给 Zed，只需要让聚合仓库通过子模块引用你仓库中的某一个 commit，并登记好版本号即可。这也解释了为什么对扩展仓库的地址、可见性、子模块提交状态有严格要求（详见下文）。

佐证参考：本仓库自身同时扮演过「宿主」角色——在 extensions/html/extension.toml、extensions/glsl/extension.toml 中可以看到 Zed 以源码形式维护的内置扩展，它们的 id、version、repository 等字段结构，与你在自己的扩展里要编写的 extension.toml 完全一致。

前置条件：动手前先逐条自检

发布申请最终由 Zed 维护者人工审查，任何不合规项都会导致发布被推迟甚至拒绝。因此在走发布流程前，请对照发布前置条件自查：

通用要求

人工验证：必须在将要提交的子模块 commit 上，于 Zed 中手动实测你的扩展可用；
避免重复造轮子：只发布扩展仓库中尚未存在的功能；如果已有扩展存在缺陷，应优先为既有扩展贡献代码（详见 FAQ 中「发现缺陷与改进建议」一节）；
不得滥用扩展 API：不得为绕过 API 当前限制而 hack；个别合理 workaround 是否被接受，由维护者酌情裁决；
扩展 ID 规范：ID 必须全局唯一、使用 kebab-case 命名、不得包含 zed 或 extension 字样，且应能准确体现扩展用途；
精简资源：只打包扩展运行所必需的资源；
采用允许的许可证：必须是许可清单之一；
用户可见文本一律使用英文；
环境边界：不得读取或修改 Zed 为你指定环境之外的任何内容。应通过 Zed Rust 扩展 API 与 Rust 标准库方法操作扩展的工作目录；其他需要用户配合的改动，应引导用户自行完成。

按扩展类型区分的专属要求

扩展类型	专属要求
语言扩展	只支持目标语言及其直接相关方言；每种语言都必须在 `extension.toml` 中定义 grammar；可额外提供 language server、debugger、snippets；ID 与名称应接近所支持语言的名字；若不含 language server，不得包含任何 Rust 代码
仅含 Language Server	ID 应以 `-language-server` 或 `-lsp` 结尾；不得捆绑 server，应通过 Zed Rust 扩展 API 下载或探测用户环境
仅含 Debugger	ID 应以 `-debugger` 结尾；不得捆绑 debug adapter，应通过 API 下载或探测
主题扩展	只提供主题，不掺其他内容；ID 应体现主题属性（如 `-theme` 结尾）
图标主题扩展	只提供图标主题；ID 应体现图标主题属性（如 `-icon-theme`、`-icons` 结尾）
仅含 Snippets	ID 应体现 snippets 属性（如 `-snippets` 结尾）；snippets 作用域应精确到对应语言，仅在合适时才使用全局作用域
MCP Server 扩展	只提供一个 MCP server；ID 应体现该角色（如 `mcp-server-` 前缀或 `-mcp-server` 后缀）；不得捆绑 server
Agent Server / Slash Command	已废弃，不再接受新提交；如需在 Zed 中提供 agent server，请发布到 ACP 注册表

许可证：从 2025 年 10 月起成为硬性要求

根据许可证要求，扩展仓库必须包含许可证文件，可选的许可证包括：

Apache 2.0
BSD 2-Clause
BSD 3-Clause
CC BY 4.0
GNU GPLv3
GNU LGPLv3
MIT
Unlicense
zlib

几个容易踩坑的细节：

文件位置：许可证文件应放在扩展根目录。若扩展位于仓库内的子目录中，许可证必须位于该子目录内，仅放在仓库根目录是无效的；可以将既有许可证 symlink 到扩展目录；
文件命名：任何以 LICENCE 或 LICENSE 为前缀（大小写不敏感）的文件都会被检查，必须与上表所列许可证之一匹配，否则添加或更新扩展的 PR 会在 CI 阶段直接失败；
适用范围：该要求仅约束扩展自身的代码（被编译进扩展二进制的部分），不包括扩展随后下载或交互的工具（如 language server 等外部依赖）；若仓库同时包含扩展代码与其他项目，也无需对其他项目重新授权。

发布全流程五步走

第一步：理解并遵守 PR 规则

聚合仓库的审查队列由维护者人工维护，因此对每一个针对扩展仓库的 PR 都有如下硬性约束：

每个 PR 只能新增或更新恰好一个扩展；
同一时刻你最多只能有 3 个处于打开状态的 PR；
对维护者反馈的回应时限为 3 周，超时 PR 将被关闭。

违反规则的 PR 会被直接关闭且不再给出额外反馈；反复违反则可能导致临时封禁甚至禁止向该扩展仓库提交。

第二步：Fork 并克隆扩展仓库

Fork zed-industries/extensions 聚合仓库；
克隆到本地并初始化子模块。

建议把仓库 Fork 到个人 GitHub 账号而非组织账号下：这样 Zed 官方人员在必要时可直接向你 PR 推送修改，从而加速发布进程。

# 请将 URL 替换为你自己的 fork 地址：
git clone https://github.com/your-username/extensions
cd extensions
git submodule init
git submodule update

第三步：提交扩展（核心操作）

向扩展仓库发起 PR，并在 PR 内完成如下两件事。

① 将扩展以 Git 子模块形式加入 extensions/ 目录，路径为 extensions/{extension-id}。注意三条约束：

子模块必须使用 HTTPS URL，不能用 SSH 形式的 git@github.com；
扩展仓库必须是公开可访问的；
检出的子模块 commit 必须存在于某个分支上，不能是游离（detached）commit。

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

② 在顶层 extensions.toml 中为你的扩展新增条目，其中的 version 必须与该 commit 上 extension.toml 中声明的 version 完全一致：

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

如果扩展位于子模块仓库的某个子目录内（例如 Monorepo），则用 path 字段指明扩展的实际位置：

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

③ 运行排序命令，确保 extensions.toml 与 .gitmodules 均保持有序状态：

pnpm sort-extensions

完成以上三步，PR 被接受并合并后，扩展即会被自动打包并发布到 Zed 扩展仓库。本仓库中的 extensions/html/extension.toml 可当作 extension.toml 字段写法的真实样例参考：其中声明了 id、name、description、version、schema_version、authors、repository，并可通过 [grammars.*]、[language_servers.*] 等表段声明语法与语言服务。

第四步：等待审查并响应反馈

PR 打开后，维护者会进行审查并可能要求修改。请牢记 PR 规则中的时限：3 周内未对维护者反馈作出回应，提交将被关闭。

关于审查的其他问题——如「审查通常需要多久」「为什么执行这样的时限」「PR 被关闭后该怎么办」——均可在发布 FAQ 中找到答案：

审查周期：多数提交会在数周内收到首次反馈，个别扩展可能长达一至两个月，目前官方无法给出承诺；
为何被关：PR 若无反馈即被关闭，通常意味着它严重违反了发布前置条件，请在重新提交前再次通读；
被关不是终点：任何时候都可以重新打开一个全新 PR，维护者会再次审查；为了保持队列精简，官方有时也更偏好「新开 PR」而非「复活旧 PR」；
为何要有前置条件：这是为了在「开放的扩展生态」与「可预期的质量标准」之间取得平衡，并避免同一用途出现多个功能重复、用户分散的近似扩展。

第五步：发布后的更新与维护

发布完成后，迭代更新同样通过 PR 完成，且更新 PR 与全新提交适用完全相同的 PR 规则。

更新子模块到远程仓库的最新 commit：

# 在聚合仓库根目录执行：
git submodule update --remote extensions/your-extension-name

同步更新 extensions.toml 中该扩展的 version 字段，同样要求与该 commit 上 extension.toml 声明的版本一致。若希望自动化这一流程，可选用社区维护的 GitHub Action。

维护方面（来自 FAQ）还需注意几点：

发布后官方并不强制要求你持续维护，但及时响应 issue 有助于所有使用者；
若在他人扩展中发现缺陷或想改进，应优先在原扩展仓库提交 issue 或 PR，而不是再发布一个功能重复的竞争扩展；
想要退出维护时，可将仓库所有权转交给新维护者，或在扩展仓库中提交 issue/PR 申请下架；若原维护者长期失联（有书面联络证明且失联满 6 周），社区成员可以 fork 替代，或由 Zed 官方将其接管至 zed-extensions 组织下继续联合维护，而该切换也并非永久——原维护者恢复响应后扩展可迁回原仓库。

从文档到源码：扩展元数据在 Zed 中如何被解析

上文反复强调「extensions.toml 的 version 必须与 commit 上 extension.toml 的 version 一致」「每个语言必须声明 grammar」等要求。这些约束并非凭空设计，而是与 Zed 对扩展的加载与解析机制一一对应：

extension.toml 是 Zed 扩展的元数据清单（本仓库的样例即展示了完整字段），Zed 通过解析它来识别扩展的 ID、版本、schema、作者、仓库地址，以及 grammar、language server 等能力声明；
子模块 commit 与 version 的强一致约束，保证了聚合仓库清单中登记的版本与实际检出的源码可复现、可审计——这正是发布 FAQ 中「每种语言必须使用自身 extension.toml 里定义的 grammar」的原因：若语言依赖它不拥有的 grammar，外部更新可能改变 Tree-sitter 解析产生的节点，从而在静默中破坏语言功能；
「只允许使用 Zed Rust 扩展 API 读写环境」对应的是扩展运行时的沙箱边界设计（见 crates/extension 与 crates/extension_api），这些约束通过发布前置条件落实为提交端的合规要求。

小结：发布前的最终 Checklist

✅ 对照发布前置条件逐条自检（类型、ID、边界、API 使用）；
✅ 在扩展根目录放置允许的许可证文件；
✅ Fork zed-industries/extensions 到个人账号并 git submodule init && git submodule update；
✅ 以 HTTPS 子模块方式加入扩展，确认 commit 非游离且仓库公开；
✅ 在顶层 extensions.toml 登记 submodule（必要时加 path）与版本号，且版本与 extension.toml 一致；
✅ 运行 pnpm sort-extensions 保持清单排序；
✅ 遵守「一 PR 一扩展」「最多 3 个开放 PR」「3 周内响应反馈」的规则，然后提交 PR；
✅ 合入后的更新：git submodule update --remote + 更新 extensions.toml 版本号，再提一个全新的更新 PR。