Zed 扩展的浏览、安装与自动管理：从 Extension Gallery 到目录结构与设置项全解析

这篇指南围绕 Zed 代码编辑器的扩展管理展开，覆盖 Extension Gallery 的打开方式、各平台安装目录结构（installed/work 子目录及其源码级定义）、以及 auto_install_extensions 与 auto_update_extensions 两个设置项的参数语义。读完你可以在任意平台快速浏览与安装扩展，理解扩展的磁盘布局，并通过 settings.json 实现"按语言自动装扩展、固定版本不更新"的自动化管理。文中知识点以 docs/src/extensions/installing-extensions.md 为骨架，并结合仓库内实现源码进行印证。

Zed 扩展生态：扩展能带来什么

扩展（Extensions）为 Zed 增加语言、主题、图标主题、AI 工具等能力，是编辑器功能扩展的主要载体。Zed 官方将语言与主题从核心代码中剥离，转为以扩展形式分发，因此许多常用语言支持都由扩展提供。当前仓库的 docs/src/extensions 目录对扩展能力进行了细分文档化：

• languages.md：扩展如何声明语言、语法高亮与 Tree-sitter 语法。
• themes.md 与 icon-themes.md：主题与文件图标主题。
• slash-commands.md、mcp-extensions.md、agent-servers.md：Agent 面板的斜杠命令、MCP 服务器接入等 AI 能力。
• debugger-extensions.md：调试器适配器扩展。
• snippets.md：代码片段扩展。
• developing-extensions.md：面向扩展开发者的构建与打包指南。

打开 Extension Gallery：浏览与安装的统一入口

扩展的浏览与安装统一在 Extension Gallery（扩展画廊）界面完成，两种打开方式等价：

• 使用默认快捷键打开，各平台定义在 assets/keymaps 的默认键位中：
  • macOS：cmd-shift-x（见 default-macos.json）
  • Linux：ctrl-shift-x（见 default-linux.json）
  • Windows：ctrl-shift-x（见 default-windows.json）
• 或通过菜单栏选择 "Zed > Extensions"。

在画廊页面中即可搜索、安装扩展；已安装扩展可通过其 ⋯ 菜单执行版本管理操作（详见下文"固定扩展版本"）。

扩展安装目录：各平台位置与磁盘布局

安装位置随操作系统而不同，规则统一由 crates/paths/src/paths.rs 中的 data_dir() 与 extensions_dir() 计算得出：

平台	Zed 数据目录 data_dir()	扩展目录
macOS	~/Library/Application Support/Zed	~/Library/Application Support/Zed/extensions
Linux	$XDG_DATA_HOME/zed（未设置时为 ~/.local/share/zed）	~/.local/share/zed/extensions
Windows	%LOCALAPPDATA%\Zed	%LOCALAPPDATA%\Zed\extensions

说明：Linux/FreeBSD 路径来自 paths.rs 中对 data_local_dir() 的分支处理，其中 XDG_DATA_HOME 未设置时回落到 ~/.local/share。在 Flatpak 环境下，源码还会优先读取 FLATPAK_XDG_DATA_HOME 环境变量再拼接 zed 目录。macOS 上的数据目录会使用 Library/Application Support 下以 Zed 命名的目录。

extensions 目录内部的两个核心子目录

按 installing-extensions.md 的说明，扩展目录下包含两个核心子目录：

• installed：存放每个扩展的源代码。以扩展包为单位，每个扩展一个子目录。
• work：存放扩展自身运行期创建的文件，例如扩展下载的语言服务器可执行文件。

这段描述可以在源码 crates/extension_host/src/extension_host.rs 的 ExtensionHost::new 初始化逻辑中得到印证——它围绕 extensions_dir 依次拼接出若干关键路径：

let work_dir = extensions_dir.join("work");
let build_dir = build_dir.unwrap_or_else(|| extensions_dir.join("build"));
let installed_dir = extensions_dir.join("installed");
let staging_dir = extensions_dir.join("staging");
let index_path = extensions_dir.join("index.json");

从源码结构可以推断，除文档提到的 installed 与 work 外，扩展目录中通常还会出现三类系统级条目，理解它们有助于排查问题：

• build：扩展构建缓存目录，ExtensionBuilder 会在此编译 Rust 与 WASM 扩展产物；
• staging：安装过程中的临时暂存目录，扩展先落盘到此、校验后再移入 installed；
• index.json：扩展索引文件，记录当前已安装扩展及其提供的资源清单。该索引在启动时被同步加载（extension_host.rs），若索引文件失效或过期，则会根据文件系统 mtime 异步重建。

每个已安装扩展的内部形态

以 installed 目录下一个典型扩展为例，其子目录中包含描述扩展元数据的 extension.toml 清单（ExtensionManifest::load 在启动时读取 extension_manifest.rs），以及编译产物 extension.wasm；若扩展携带 Tree-sitter 语法或 Rust 动态库，则会包含对应编译目标目录。扩展打包与构建的完整约束可参考 developing-extensions.md。

列出已安装扩展

由于扩展名即为其在 installed 下的子目录名，官方 settings 文档给出的排查命令是直接列目录：

# macOS
ls ~/Library/Application\ Support/Zed/extensions/installed/

# Linux
ls ~/.local/share/zed/extensions/installed

# Windows (PowerShell)
Get-ChildItem "$env:LOCALAPPDATA\Zed\extensions\installed" -Name

自动安装扩展：用 auto_install_extensions 声明式管理

要自动化"安装/卸载扩展"的行为，可配置 auto_install_extensions 设置，该设置项的权威说明位于 docs/src/reference/all-settings.md。

• 设置项：auto_install_extensions
• 默认值：{ "html": true }
• 取值类型：以扩展名为键、布尔值为值的对象，其中 true 表示强制安装，false 表示绝不安装

例如以下配置会确保 html 与 dockerfile 两个扩展始终可用，同时明确禁止安装 docker-compose：

{
  "auto_install_extensions": {
    "html": true,
    "dockerfile": true,
    "docker-compose": false
  }
}

该设置的对象结构在配置架构源码 crates/settings_content/src/extension.rs 中被实现为 HashMap<Arc<str>, bool>，其默认值为 { "html": true }，即 HTML 语言支持默认随 Zed 自动装载，这正是"开箱即用地获得语言支持"的实现载体——Zed 依赖此机制把由扩展提供的语言能力在首次启动时自动就位。将该设置写入用户的 settings.json（配置文件位于 config_dir()，Linux 下为 ~/.config/zed/settings.json）即可生效。

固定扩展版本：用 auto_update_extensions 关闭自动更新

默认情况下，Zed 在每次启动时会对所有已安装扩展进行自动更新。如果某个扩展的新版本引入了兼容性问题，你可以通过 auto_update_extensions 将特定扩展"钉"在当前已安装版本：

• 设置项：auto_update_extensions
• 默认值：{}（即全部自动更新）

{
  "auto_update_extensions": {
    "html": false
  }
}

此外，还有一条无需手写配置的捷径：在 Extension Gallery 页面中，从某个扩展的 ⋯ 菜单中选择 Install Another Version…，可以回退或安装指定历史版本——该操作会自动写入 auto_update_extensions 并固定该扩展版本。

实操小结与深入阅读

一次完整的扩展管理闭环可以总结为：用画廊浏览（默认快捷键 cmd/ctrl-shift-x）→ 观察 installed 目录确认磁盘形态 → 需要随语言自动装载时在 settings.json 配置 auto_install_extensions → 需要锁版本时通过 auto_update_extensions 或画廊的 "Install Another Version…" 固定版本。

如果你希望进一步深入，可按需阅读仓库中的以下文档：

• 扩展的自动安装/自动更新完整参数： all-settings.md（auto_install_extensions、auto_update_extensions 小节）
• 扩展开发与打包规范：developing-extensions.md
• 语言与主题扩展：languages.md、themes.md
• 扩展能力相关源码：扩展宿主路径初始化见 crates/extension_host/src/extension_host.rs，路径解析见 crates/paths/src/paths.rs，设置项数据结构见 crates/settings_content/src/extension.rs。