Zed 扩展发布后的更新与维护指南：子模块迭代、版本同步与长期维护策略

扩展发布并非终点。在 Zed 中，扩展一旦被合入扩展仓库并进入官方扩展注册表，后续的 bug 修复、功能升级与版本发布都走一套独立的“更新流程”；而当你不打算继续维护时，也有一套清晰的退出与交接机制。本文基于 Zed 官方发布文档中 Updating an Extension 一篇展开，完整讲解已发布扩展如何通过 Git 子模块提交更新、如何同步 extensions.toml 中的版本号、如何自动化发布，并结合 Zed 仓库内扩展清单（extension.toml）的解析源码与 发布指南、FAQ 的配套规则，覆盖“发布后迭代、停止维护、失联接管”的完整生命周期。读完后你将能独立完成一次 Zed 扩展的版本升级，并知道在放弃维护时该做什么、不该做什么。

一、更新流程的整体脉络：为什么是“改注册表仓库”而不是“重新发布”

Zed 的扩展发布机制与大多数独立应用商店不同：扩展本体始终托管在你自己公开的 Git 仓库中，而 Zed 官方侧只维护一个集中式的“扩展注册仓库”（即 zed-industries/extensions）。该仓库通过 Git submodule（子模块） 指回每个扩展的仓库，并通过顶层 extensions.toml 记录每个扩展的路径与当时锁定的版本号。

因此，发布一个新版本的实质是：向扩展注册仓库提交一次 PR，把子模块指针前移到你的扩展仓库的最新 commit，并把 extensions.toml 中该扩展的 version 字段同步为新版本号。Zed 的扩展托管与安装逻辑负责按这个版本号去对应 commit 处读取扩展清单并打包。关于注册表的结构与新增扩展的提交方式，可先阅读 Publishing Guide 与 Publishing Extensions 总览。

一个关键前提：扩展注册仓库中记录的 extensions.toml，与扩展自己仓库根目录下的 extension.toml 是两份不同的文件。前者是注册表的索引，后者才是 Zed 实际加载并解析的“扩展清单”（manifest）。更新版本时必须让两者保持一致。

二、扩展清单 extension.toml：版本号从哪儿来

要理解“同步版本号”究竟在同步什么，需要先明确扩展自己仓库中的 extension.toml 长什么样。在 Zed 主仓库的源码中，扩展清单由 ExtensionManifest 结构体承载，定义于 extension_manifest.rs，核心字段包括：

• id：扩展唯一标识（kebab-case，且不含 zed/extension 字样，规则见 发布前提）；
• name：展示名称；
• version：语义化版本号，发布迭代时每次都要递增并同步；
• schema_version：清单结构版本；
• 以及按需声明的 grammars、languages、language_servers、themes、icon_themes、snippets、debug_adapters、context_servers、capabilities 等能力入口。

Zed 通过 extension_manifest.rs 中 ExtensionManifest::load 从扩展目录读取 extension.toml 并反序列化；仓库内测试夹具给出了最小可用的清单样例（见 extension_builder.rs）：

id = "test-manifest"
name = "Test Manifest"
version = "0.0.1"
schema_version = 1

snippets = "./snippets/snippets.json"

同时 extension_api/README.md 也说明了 extension.toml 位于扩展目录根、是整个扩展 API 的声明入口；新建扩展时 extension_cli 也会为你生成一份初始化的清单。值得一提的是，在 extension_manifest.rs 中仍保留了对旧版 extension.json（OldExtensionManifest）的兼容解析（extension_manifest.rs），可见 manifest 格式经历过一次从 JSON 到 TOML 的迁移。

在 Zed 侧，扩展被 extension_host 这类运行时按“注册表索引中记录的版本 → 对应 commit 的 extension.toml”进行加载与更新比较。可以推断：注册表 extensions.toml 中 version 与扩展仓库 extension.toml 中 version 不一致，就会导致索引错位——这正是官方更新流程反复强调“Make sure the version matches”的原因。

三、发布一个扩展新版本：标准两步流程

Updating an Extension 给出的更新流程非常收敛：向 zed-industries/extensions 仓库开一个 PR，并在 PR 中完成两步操作。完整步骤如下：

1. 把扩展子模块前移到新版本对应的 commit。 在 zed-industries/extensions 仓库根目录执行：

# 在扩展注册仓库的根目录执行
git submodule update --remote extensions/your-extension-name

--remote 会从子模块对应的远端拉取最新内容，并把该子模块的工作区指针更新到你扩展远端仓库最新的可用 commit。

2. 更新顶层 extensions.toml 中该扩展条目的 version 字段。
   • 务必确保这里的 version 与该 commit 处 extension.toml 里声明的版本完全一致。

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

PR 合入后，新版本即被打包并发布到 Zed 扩展注册表，用户在 Zed 内即可检测到更新。

3.1 结合提交（publishing）规则理解更新 PR 的约束

更新 PR 与首次提交的 PR 适用同一套 Pull Request 规则（见 publishing-guide.md）：

• 每个 PR 只能新增或更新恰好一个扩展；
• 同一时间你最多只能有三个处于打开状态的 PR；
• 维护者在 PR 中给出反馈后，若你3 周内不回应，PR 将被关闭。

违反上述规则的 PR 会被直接关闭且不再另行解释；屡次违反甚至可能导致提交资格被临时暂停或封禁。

3.2 更新时同样要守住的提交约束

首次提交（publishing-guide.md）中关于子模块形态的要求，在更新 PR 中依然生效，可作为自查项：

• 子模块必须使用 HTTPS URL 而非 SSH URL（[e-mail]）；
• 扩展仓库必须公开可访问；
• 被检出的子模块 commit 必须处于某个分支上，不能是一个游离（detached）commit——否则无法通过 --remote 干净地前移；
• 若扩展位于子模块仓库内的子目录，需用 path 字段指明扩展所在位置：

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

• 提交前运行 pnpm sort-extensions，确保 extensions.toml 与 .gitmodules 的条目顺序合规。

四、自动化发布：把两步更新交给 CI

如果不想每次发版都手动切仓库、拉子模块、改版本号，官方文档推荐社区维护的自动化 Action（huacnlee/zed-extension-action）来完成这套流程。其基本思路通常是在你自己的扩展仓库中配置工作流：当打上形如 v* 的标签（tag）或推送 release 时，由该 Action 自动帮你把新的版本号与子模块 commit 提交到 zed-industries/extensions 仓库。典型触发方式（示意，具体以 Action 文档为准）：

on:
  push:
    tags:
      - "v*"

使用这类自动化时仍需注意：自动化只是替你执行“同步子模块 + 同步 version + 开 PR”三个机械动作，PR 规则（一次只动一个扩展、回复时限等）仍然适用，因此若自动开出的 PR 迟迟无人回应，同样可能被关闭。

五、更新之后的维护：bug、改进建议与“可以不维护”

新版本发布不代表维护义务的开始。官方 FAQ 明确：发布之后，官方对扩展所有者没有任何强制性的后续维护要求。但在实际运营层面，有以下几条建议性的协作规范：

• 发现 bug 或想改进某个扩展：先到该扩展的原始仓库提交 issue 或提改进，而不是另起炉灶发布一个“竞品扩展”——把精力集中到一处，既方便所有者管理，也避免用户面对一堆同质化扩展无从选择。若所有者长期不回应，再考虑后续的接管流程。
• 响应建议：扩展第一天上线时往往并不完美，bug 与改进诉求会出现。虽然不维护也不违规，但在合理时间窗内回应报告，对所有人（包括你的用户群）都更有利。

完整问答收录于 FAQ。

5.1 前置要求同样适用于老扩展

FAQ 特别强调：“发布前提”对已发布的扩展同样生效，更新 PR 与首次提交被置于同一质量标准下审视。唯一的例外是扩展 ID 约束——由于 ID 一经发布便不可更改，既有扩展的 ID 会原样保留。

六、退出与接管：当你不再维护一个扩展时

优先级变化、转向其他方向都是常态。作为当前所有者，停止维护有两条体面路径（详见 FAQ）：

• 将扩展仓库所有权转移给新的维护者；
• 在 zed-industries/extensions 仓库开 issue 或 PR，请求移除你的扩展。

此外也完全可以保留原样——官方 FAQ 坦言，很多扩展更新寥寥甚至从未更新，却仍拥有大量满意用户。扩展“不更新”与“被移除”之间没有必然联系。

6.1 所有者失联时的接管条件

为避免已发布扩展“僵尸化”损害用户体验，当所有者长期失联时，第三方可以发起接管：

• 贡献者可 fork 该扩展，并提议将 fork 作为现有扩展的替代品；
• Zed 官方人员可将扩展 fork 至 zed-extensions 组织，由社区与 Zed 官方共同继续维护。

但官方只会在这两种情形满足其一后才采取行动：

1. 现任所有者给出了书面许可；
2. 存在尝试建立联系的书证，且所有者对其至少 6 周未作回应。

两者皆无，则扩展保持由现任所有者持有。并且这种接管并非不可逆：若原所有者日后恢复响应，扩展可以被切回原仓库。

七、仓库内的源码佐证：去哪里核对这套机制

作为 Zed 主仓库的读者，你可以在本仓库内直接验证上文的每一项描述：

• 扩展清单结构：crates/extension/src/extension_manifest.rs 定义了 ExtensionManifest，其中 version 与 schema_version 字段即更新流程中需要同步的对象；
• 清单加载逻辑：crates/extension/src/extension_manifest.rs 展示 Zed 如何定位扩展目录并加载 extension.toml；
• 清单测试样例：crates/extension/src/extension_builder.rs 与同一文件稍后段落给出带 snippets/不带 snippets 的最小 extension.toml，可作为你维护自己清单格式时的参照；
• 扩展清单的权威说明：crates/extension_api/README.md 介绍 extension.toml 在扩展目录中的角色；
• 扩展脚手架写入：crates/extension_cli/src/main.rs 展示初始化时如何生成清单文件；
• 配套发布文档：发布总览、发布指南、发布前提、许可要求、FAQ；
• 扩展类型能力：若你的扩展随版本新增语言/语法能力，相关约束见 languages.md。

八、更新前自检清单

综合官方文档与上文源码佐证，在你发出更新 PR 前建议逐项核对：

• [ ] 扩展仓库的最新 commit 已充分自测，且该 commit 处于某个分支上（非 detached）；
• [ ] git submodule update --remote extensions/<your-extension> 已在注册仓库根目录执行，子模块指针正确前移；
• [ ] 注册仓库 extensions.toml 中 version 与目标 commit 处扩展仓库 extension.toml 的 version 完全一致且已递增；
• [ ] 若扩展位于子模块子目录，path 字段仍指向正确位置；
• [ ] 已运行 pnpm sort-extensions；
• [ ] PR 只涉及一个扩展，且自己名下打开的 PR 数不超过三个；
• [ ] 准备好及时回应维护者反馈（3 周时限）；
• [ ] 更新内容未引入发布前提之外的新资源或越权行为，许可证仍属于允许列表（见 许可要求）。

完成以上步骤并等待 PR 合入后，新版本就会进入 Zed 扩展注册表供用户更新。若后续不再维护，按第六节的路径退出即可——发布、迭代、退出三阶段至此形成完整闭环。