Zed 编辑器快速上手：环境搭建、核心命令与导航入门实战指南

Zed 是一款开源的高性能代码编辑器，内置协作（collaboration）与 AI 能力，由 Atom 与 Tree-sitter 原班人马打造。本文以官方文档 getting-started.md 为主线，结合本仓库源码讲解从打开第一个项目、掌握快捷键、配置编辑器与语言，到体验 Agent 面板的完整入门路径。读完你将具备从零上手 Zed、按需定制工作区布局与保存格式行为，并了解欢迎页与布局系统底层实现的能力。

快速开始：从 Welcome 页到你的第一个项目

Welcome 页：Zed 的“主页”

当你不打开任何文件夹启动 Zed 时，主编辑区会显示 Welcome（欢迎）页。欢迎页集中提供了几个高频快捷操作：打开文件夹、克隆仓库（clone a repository） 以及查看文档；一旦打开文件夹或文件，欢迎页即自动消失。若将编辑器拆分为多个 pane，欢迎页只会在中央 pane 为空时出现，其余 pane 显示标准的空状态。

想要重新唤出欢迎页，有两种方式：

1. 关闭中央 pane 中的所有项目/文件；
2. 打开命令面板，搜索 Welcome 并执行（对应源码中的 ShowWelcome 动作）。

源码层面，欢迎页实现在 welcome.rs 中：WelcomePage 作为一个可序列化的 workspace item（其持久化标识为 "WelcomePage"，并通过 WelcomePagesDb 保存“是否处于打开状态”），渲染时使用 key_context("Welcome") 建立独立键盘上下文，支持上下选择与回车打开最近项目。当存在最近打开的工程时，标题会切换为 “Welcome back to Zed” 并展示最近项目列表（最多 5 条）；若 AI 功能已启用，还会在页面底部渲染一张 “Collaborate with Agents” 的入口卡片（见 welcome.rs 中的 render_agent_card）。

第 1 步：打开一个项目

Zed 提供了两种打开工程的方式。

方式一：命令行启动

zed ~/projects/my-app

把 ~/projects/my-app 替换为你自己的项目目录即可。Zed 会把 CLI 参数解析为要打开的路径（相关实现位于 cli crate）。

方式二：编辑器内打开

在 macOS 上按 Cmd+O，在 Linux/Windows 上按 Ctrl+O，即可在 Zed 内选择文件夹打开。

关于新窗口的行为，有两个细节值得注意：

• 默认情况下，新项目会打开在**当前窗口的 threads sidebar（会话侧栏）**中，而不是新开窗口；
• 若希望强制在新窗口打开，可以：
  • 命令行追加 -n 参数：zed -n ~/projects/my-app；
  • 在 “Open Recent（最近打开）” 列表中选中项目后按 Cmd+Enter（macOS）/ Ctrl+Enter（Linux/Windows）。

窗口与会话的更多细节，见 Windows & Projects。

第 2 步：掌握核心命令

下表是本入门指南要求熟练掌握的高频操作，请务必记住：

动作	macOS	Linux/Windows
命令面板（Command palette）	Cmd+Shift+P	Ctrl+Shift+P
跳转到文件（Go to file）	Cmd+P	Ctrl+P
跳转到符号（Go to symbol）	Cmd+Shift+O	Ctrl+Shift+O
在项目中搜索（Find in project）	Cmd+Shift+F	Ctrl+Shift+F
切换终端（Toggle terminal）	Ctrl+`	Ctrl+`
打开设置（Open settings）	Cmd+,	Ctrl+,

其中命令面板（Cmd+Shift+P）是你访问 Zed 中每一个动作的入口——如果忘记了某个快捷键，直接在命令面板里搜动作名即可。这些动作与快捷键的完整注册表，可以在默认键位配置 default-macos.json 与 default-linux.json 中逐一核对，Zed 的键位映射使用 "cmd-shift-p": "workspace::CommandPalette" 这样的 JSON 结构，方便你自定义覆盖。

面板布局：Agentic 与 Classic 的切换

当希望 Agent Panel（代理面板）与 Threads Sidebar（会话侧栏）并排出现在左侧、以“AI 协作优先”的方式工作时，可通过标题栏用户菜单中的 Panel Layout > Agentic 切换；对应动作是 workspace::UseAgenticLayout。若要恢复以编辑器为中心的传统布局，选择 Panel Layout > Classic（或执行 workspace::UseClassicLayout）。

源码证据：这两个动作定义并注册于 title_bar.rs，内部调用 set_window_layout 分别将窗口布局设置为 WindowLayout::Agent(None) 与 WindowLayout::Editor(None)；而布局类型的定义位于 agent_settings.rs 的 enum WindowLayout { Editor(..), Agent(..), Custom(..) }，说明 Zed 将窗口布局作为可配置状态持久化管理。另一个值得注意的实现细节：当 AI 功能被禁用（disable_ai）时，Zed 会在命令面板过滤器中隐藏这两个布局动作（见 title_bar.rs），避免用户在无 AI 场景下误入 Agentic 布局。

第 3 步：配置你的编辑器

按 Cmd+,（macOS）或 Ctrl+,（Linux/Windows）打开 Settings Editor（设置编辑器）。它本质是一个可搜索的配置面板——直接搜索任意设置项的名称即可定位并修改，所有变更会实时写入你的 settings.json。首次使用建议调整的常见项：

• 主题（Theme）：按 Cmd+K Cmd+T（macOS）或 Ctrl+K Ctrl+T（Linux/Windows）打开主题选择器。仓库内置了 ayu、gruvbox、one 等多套主题（见 themes），也支持通过扩展安装第三方主题。
• 字体（Font）：在设置中搜索 buffer_font_family。默认值是 ".ZedMono"（见 default.json），可改为 "ui_font_family" 之外你系统已安装的任意字体族。
• 保存时格式化（Format on save）：搜索 format_on_save 并设为 on。

围绕 format_on_save，建议阅读 default.json 中完整的注释，因为它的取值远比布尔开关丰富：

• "off"：不自动格式化（全局默认值）；
• "on"：保存时格式化整个缓冲区；
• "modifications"：仅格式化有未提交更改（unstaged changes）的行，在无 git diff 或语言服务器不支持 range formatting 时跳过；
• "modifications_if_available"：同上，但当无法使用 range formatting 时回退为格式化整个缓冲区。

同时要留意一个组合陷阱：如果开启了“延迟自动保存（autosave with delay）”，format_on_save 会被忽略。

格式化的执行引擎由 formatter 设置控制，默认 "auto"（自动在 Prettier 集成与语言服务器之间选择）。它可以取多种值："language_server"（用当前语言服务器）、指定某个 LSP 如 {"language_server": {"name": "ruff"}}、外部命令 {"external": {"command": "prettier", "arguments": ["--stdin-filepath", "{buffer_path}"]}}、"prettier"、代码动作如 {"code_action": "source.fixAll.eslint"}，甚至可以传一个按顺序执行的数组。Zed 还会为多种主流语言在语言专属配置中默认开启 format_on_save: "on"（见 default.json 附近的语言块），这就是“装好即用”的来源。

第 4 步：配置你的语言

Zed 对大量编程语言提供开箱即用的支持（内置基于 Tree-sitter 的语法高亮与语言服务器配置，仓库中 grammars 与 languages 两个 crate 即为实现所在）。对于其余语言，通过扩展安装：

1. 按 Cmd+Shift+X（macOS）或 Ctrl+Shift+X（Linux/Windows）打开 Extensions（扩展）面板；
2. 搜索你的语言名（例如 HTML、GLSL、proto 等，仓库内 extensions 目录收录了若干内置扩展示例）；
3. 点击 Install 安装。

各语言更细化的配置说明，见 Languages。

第 5 步：体验 AI 功能

Zed 内置 AI 辅助能力，无需额外安装即可尝试：

• 按 Cmd+Shift+A（macOS）或 Ctrl+Shift+A（Linux/Windows）打开 Agent Panel（代理面板），开始一次对话；
• 需要行内辅助时，使用 Cmd+Enter（macOS）或 Ctrl+Enter（Linux/Windows）。

在仓库源码中，Agent 面板、内联助手及其配置项分散在 agent、agent_ui、agent_settings 等 crate 中；例如窗口布局与代理行为相关的全部设置都沉淀于 agent_settings.rs。如何配置各家模型供应商、可用功能边界等，请阅读 AI Overview。

从其他编辑器迁移过来？

如果此前长期使用别的编辑器，Zed 准备了针对性的迁移指南：

• VS Code — 导入设置、映射键位、寻找等价功能
• IntelliJ IDEA — 适应 Zed 的导航与重构方式
• PyCharm — 在 Zed 中搭建 Python 开发环境
• WebStorm — 配置 JavaScript/TypeScript 工作流
• RustRover — 在 Zed 中进行 Rust 开发

如果你不打算放弃肌肉记忆，也可以直接启用熟悉的键位模式：

• Vim 模式：在设置中启用 vim_mode。Zed 内置了完整的 Vim 模拟层（对应 vim crate，内置超过 300 个键位测试用例），详见 Vim Mode。
• Helix 模式：在设置中启用 helix_mode，详见 Helix Mode。

加入社区与贡献

Zed 完全开源，欢迎以“为开源做贡献、报告缺陷或提出特性建议”的方式参与：

• 本项目即 Zed 的完整源码仓库，入门贡献流程请先阅读 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md；
• 官方文档站点源码也收录在 docs/src，写作规范与构建方式见 docs/README.md 与 book.toml；
• 更活跃的实时讨论与社区反馈渠道包括 Zed 官方 Discord 服务器、GitHub Discussions 讨论区以及 r/ZedEditor 社区——你可以在官方文档对应页面找到入口。

结合本文的学习路径，建议的实践顺序是：先在命令行用 zed 打开一个真实项目 → 用命令面板和「跳转到文件」快速熟悉导航 → 调整主题、字体与 format_on_save → 按需安装语言扩展 → 最后尝试 Agent Panel，并在 Agentic 与 Classic 两种布局间来回切换，找到最适合自己的工作区形态。