# 方式一：Homebrew（官方文档推荐）
brew install --cask zed            # stable
brew install --cask zed@preview    # preview 渠道

# 方式二：官网直接下载
# https://zed.dev/download 下载 dmg 安装；preview 版在 https://zed.dev/releases/preview

# 方式一：winget（官方包）
winget install -e --id ZedIndustries.Zed

# 方式二：官网下载安装包
# https://zed.dev/download 获取安装器；preview 版在 https://zed.dev/releases/preview

# stable（默认）
curl -f https://zed.dev/install.sh | sh

# 指定版本
curl -f https://zed.dev/install.sh | ZED_VERSION=0.216.0 sh

# preview 渠道（比 stable 提前约一周收到更新）
curl -f https://zed.dev/install.sh | ZED_CHANNEL=preview sh

# Arch 官方仓库
sudo pacman -S zed
# AUR：zed-git / zed-preview / zed-preview-bin
# Fedora（Terra 仓库）：zed
# Homebrew on Linux：brew install --cask zed
# Conda：conda install -c conda-forge zed
# Nix（unstable）：zed-editor
# Flathub：dev.zed.Zed

# 从 https://cloud.zed.dev/releases/stable/latest/download?asset=zed&arch=x86_64&os=linux 下载
mkdir -p ~/.local
tar -xvf zed-linux-x86_64.tar.gz -C ~/.local
ln -sf ~/.local/zed.app/bin/zed ~/.local/bin/zed

# 可选：集成 XDG 桌面环境
install -D ~/.local/zed.app/share/applications/dev.zed.Zed.desktop -t ~/.local/share/applications
sed -i "s|Icon=zed|Icon=$HOME/.local/zed.app/share/icons/hicolor/512x512/apps/zed.png|g" ~/.local/share/applications/dev.zed.Zed.desktop
sed -i "s|Exec=zed|Exec=$HOME/.local/zed.app/bin/zed|g" ~/.local/share/applications/dev.zed.Zed.desktop

# 命令行直接打开远程项目
zed ssh://[<user>@]<host>[:<port>]/<path>
# 或热链接
zed://ssh/[<user>@]<host>[:<port>]/<path>

cargo build --release --package remote_server
llvm-objcopy --strip-debug target/release/remote_server
# 上传到 ~/.zed_server/zed-remote-server-stable-<版本>，版本号必须与本地 Zed 完全一致

# 1. 克隆仓库
git clone https://github.com/zed-industries/zed.git
cd zed

# 2. 安装 rustup（官方文档使用 rustup 默认工具链，未要求 nightly）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 3. 安装系统依赖（Linux）
script/linux        # 内容即所需包列表，也可手动安装

# 4. 构建运行
cargo run               # debug 版编辑器
cargo run -p cli        # release 主入口是 cli crate
cargo test --workspace  # 跑测试

# 5. 安装本地构建到系统
./script/install-linux  # 安装 zed 到 ~/.local/bin 并注册 .desktop

常用设置项速览（完整列表见官方 all-settings 参考）：

| 设置 | 默认值 | 说明 |
| --- | --- | --- |
| `theme` | One Dark（深/浅可分设） | 主题，可 `{"mode":"system","light":...,"dark":...}` |
| `buffer_font_family` / `buffer_font_size` | Zed 内置字体 / 15 | 编辑区字体与字号 |
| `buffer_font_fallbacks` | null | 字体回退列表（macOS/Windows），中文乱码时把中文字体加进来 |
| `ui_font_fallbacks` / `terminal.font_fallbacks` | null | UI / 终端字体回退 |
| `tab_size` | 4 | 缩进宽度 |
| `format_on_save` | "on" | 保存时格式化 |
| `autosave` | on_focus_change | 自动保存时机 |
| `vim_mode` | false | Vim 模式开关 |
| `disable_ai` | false | 关闭全部 AI 功能 |
| `proxy` | null | 网络代理，如 `http://proxy.example.com:8080` |
| `lsp` | null | 按语言服务器覆盖 `initialization_options` / `settings` |
| `languages` | — | 按语言覆盖设置 |
| `terminal.*` | — | 终端字体、环境等 |
| `ssh_connections` | [] | 远程主机列表（含 `args`、`port`、`username`、`port_forwards` 等） |
| `context_servers` | {} | MCP 服务器配置 |
| `language_models` | {} | LLM 提供方配置 |
| `agent` | — | Agent 相关（默认模型、权限、压缩等） |

**LSP 覆盖示例**（rust-analyzer 用 clippy 检查；YAML 服务器运行时设置）：

```json [settings]
{
  "lsp": {
    "rust-analyzer": {
      "initialization_options": {
        "check": { "command": "clippy" }
      }
    },
    "yaml-language-server": {
      "settings": {
        "yaml": { "keyOrdering": true }
      }
    }
  }
}

## 七、启动、后台常驻、开机自启、改端口

Zed 是桌面编辑器，不存在"服务端常驻"的常规需求；日常启动与 CLI 用法如下：

```sh
zed                     # 打开欢迎窗口
zed .                   # 当前目录作为项目打开
zed path/to/file.rs     # 打开单个文件
zed --foreground .      # 前台模式（排障用，日志直出终端）
zed --system-specs      # 打印系统规格（报 issue 用）
zed --uninstall         # 卸载脚本安装的 Zed（会询问是否保留配置）

# ~/.config/systemd/user/zed-cli-daemon.service
[Unit]
Description=Zed CLI (warm start)

[Service]
Type=oneshot
ExecStart=/usr/bin/zed --foreground %h/projects/demo
RemainAfterExit=no

[Install]
WantedBy=default.target

systemctl --user enable zed-cli-daemon.service

底层使用 `ssh -L` 转发；默认只绑定 localhost，`local_host: "0.0.0.0"` 可对局域网开放。

**Linux 桌面集成**：tar.gz 安装需按 5.3 节安装 `.desktop` 文件；脚本安装自动完成。

## 八、功能实操教程

### 8.1 启用 AI Agent（Zed Agent）

1. 打开 Agent Panel：命令面板执行 `agent::NewThread`，或点状态栏 ✨ 图标；
2. 在 **Settings → AI → LLM Providers**（`agent::OpenSettings`）里登录 Zed 托管模型，或填入提供方 API Key（Key 存入系统钥匙串，不落 settings.json；环境变量优先级更高，如 `ANTHROPIC_API_KEY`）；
3. 在消息编辑器输入需求回车；`@` 可引用文件、目录、符号、历史线程、Skills、诊断、分支 diff、URL；
4. Agent 修改文件后，点 Review Changes（或面板上的折叠条）在 multi-buffer diff 中逐 hunk 接受 / 拒绝；
5. 长会话用 `/compact` 手动压缩上下文，或依赖 `agent.auto_compact`（默认 90%）自动压缩；点 `+` → New From Summary 可用摘要续接新线程。

### 8.2 配置 DeepSeek / OpenRouter / 自建 OpenAI 兼容端点

```json [settings]
{
  "language_models": {
    "deepseek": {
      "api_url": "https://api.deepseek.com/v1",
      "available_models": [
        { "name": "deepseek-chat", "display_name": "DeepSeek Chat", "max_tokens": 128000 }
      ]
    },
    "open_router": {
      "api_url": "https://openrouter.ai/api/v1",
      "available_models": [
        { "name": "openrouter/auto", "display_name": "Auto", "max_tokens": 2000000, "supports_tools": true }
      ]
    },
    "openai_compatible": {
      "my-gateway": {
        "api_url": "https://my-gateway.internal/v1",
        "available_models": [
          { "name": "my-model", "max_tokens": 128000, "reasoning_effort": "high",
            "capabilities": { "tools": true, "images": false, "chat_completions": true } }
        ]
      }
    }
  },
  "agent": { "default_model": { "provider": "openrouter", "model": "openrouter/auto" } }
}

# Ollama
ollama pull qwen2.5-coder
ollama serve
# LM Studio
lms get qwen2.5-coder-7b && lms server start
# llama.cpp（router 模式）
llama serve -hf unsloth/gemma-4-26B-A4B-it-GGUF:BF16

方式一：命令面板 → zed::Extensions → 搜索 context-servers 过滤器安装扩展
        （Context7、GitHub、Puppeteer、Figma、Brave Search、Gem、Resend 等）
方式二：Settings → AI → MCP Servers → Add Server → Add Local / Remote Server
        （写入 settings.json 的 context_servers 节点）

zed ssh://dev@203.0.113.10:2222~/repos/api

editor::RestartLanguageServer   # 命令面板重启语言服务器（诊断卡死首选）
zed::OpenLog                    # 查看日志定位 LSP 报错

首次启动欢迎页也可勾选开启；命令面板 `workspace::ToggleVimMode` 随时切换。主题：内置主题在 Settings Editor 搜索 Theme 即换；更多主题从扩展市场安装（`zed::Extensions`）。快捷键：`key-bindings` 文档所述，用户快捷键写在 `~/.config/zed/keymap.json`。

### 8.8 Tasks / Debugger / REPL / 协作

- **Tasks**：在 `.zed/tasks.json` 定义任务模板（构建、测试等），命令面板或快捷键触发，可绑定快捷键；
- **Debugger**：内置 DAP 调试器，断点 / 单步 / 变量查看，适配器可由扩展提供；
- **REPL**：编辑器内 Jupyter 式单元格执行；
- **协作**：加入频道（`collaboration/channels` 文档）、共享项目实时共同编辑；macOS 12.3+ 支持屏幕分享。

## 九、全套报错故障排查

| # | 现象 | 原因 | 解决 |
| --- | --- | --- | --- |
| 1 | Linux 启动报 `/lib64/libc.so.6: version 'GLIBC_2.29' not found` | 系统 glibc 过旧 | 升级系统，或按 5.5 节源码编译 |
| 2 | Linux 报 `Zed failed to open a window: NoSupportedDeviceFound` | Vulkan 找不到兼容 GPU | 用 `vkcube`（vulkan-tools 包）排查，在 X11/Wayland 两种模式各试一次；安装 Vulkan 驱动 |
| 3 | 报 `ERROR_INITIALIZATION_FAILED` / `GPU Crashed` / `ERROR_SURFACE_LOST_KHR` | GPU 驱动或选卡问题 | 更换/升级驱动；用 `ZED_DEVICE_ID=0x2484 zed`（`lspci -nn \| grep VGA` 查 ID）或 `MESA_VK_DEVICE_SELECT` 强制指定显卡 |
| 4 | AMD GPU 启动崩溃（Broken Pipe） | 驱动栈问题 | 改用 RADV/Mesa 驱动；若装了 `amdvlk`，卸载 `amdvlk`、`lib32-amdvlk` 并改装 `vulkan-radeon` |
| 5 | 双显卡笔记本选错 GPU | 默认用了集显 | `/etc/prime-discrete` 设为 `on`；或运行时 `DRI_PRIME=1 zed` |
| 6 | 无法打开文件 / 点链接无效 | 缺 XDG 桌面门户 | 安装并启用 `org.freedesktop.portal.FileChooser` 与 `OpenURI`（Hyprland 等窗口管理器需自配 backend） |
| 7 | API Key / 登录态记不住 | 缺密钥环 | 安装 `gnome-keyring`、`KWallet` 或 `keepassxc` 等提供 `org.freedesktop.Secrets` 的组件 |
| 8 | 报 `Could not start inotify` / "too many open files" | inotify 实例/ watches 或 fd 不足 | `sudo sysctl fs.inotify.max_user_instances=1024`、`fs.inotify.max_user_watches=64000`；`ulimit` 与 `/etc/security/limits.conf` 调大 |
| 9 | Linux 无声 / 声音设备错误 | ALSA 未接 PipeWire/PulseAudio | `sudo apt install pipewire-alsa`，并在 `~/.asoundrc` 配 `pcm.!default { type pipewire }` |
| 10 | Linux 中文 / 图标字体显示异常 | 字体回退缺失 | 设置 `buffer_font_fallbacks` / `ui_font_fallbacks` 指向 Noto CJK、Nerd Font 等；X11 下可用 `ZED_FONTS_GAMMA`、`ZED_FONTS_GRAYSCALE_ENHANCED_CONTRAST` 微调渲染 |
| 11 | X11 缩放错误（界面过大/过小） | DPI 检测问题 | `xrdb -merge` 设置 `Xft.dpi`，或 `GPUI_X11_SCALE_FACTOR=1.5 zed` |
| 12 | Windows 启动白屏 / 空白窗口 | GPU 不满足 DX11 或驱动问题 | `dxdiag` 确认 DirectX 11；更新 Intel/AMD/NVIDIA/Qualcomm 驱动；禁用第三方软件对硬件加速的拦截；无扩展 + 默认配置启动排查 |
| 13 | Windows 终端 / Git 异常 | 激活脚本或 PATH 问题 | 升级 Zed 至最新；确认 Git Bash / PowerShell 在 PATH 中 |
| 14 | SSH 远程凭据弹窗不出现 | 凭据管理器冲突 | 使用图形 askpass 对话框；确认 ssh-agent 运行、ssh.exe 在 PATH |
| 15 | 启动即崩溃且与工作区相关 | 工作区 SQLite 数据库损坏 | 移走数据库目录（Linux `~/.local/share/zed/db`，macOS `~/Library/Application Support/Zed/db`，Windows `%LOCALAPPDATA%\Zed\db`）后重启（会重置最近项目、标签等） |
| 16 | 诊断陈旧 / 跳转定义失效 | 语言服务器状态异常 | 命令面板执行 `editor::RestartLanguageServer` |
| 17 | Agent 报 "Max tokens reached" | 响应或上下文超模型上限 | 新开线程 / 选更大上下文模型 / 拆小任务 / 清理工具输出；`/compact` 压缩 |
| 18 | MCP 服务器状态点非绿色 / 工具不被调用 | 配置缺参数或模型不支持 | 按 provider 文档补全 command/args/env；MCP Servers 页查看状态；提示词中点名 MCP 服务器，或建仅含 MCP 工具的 Profile |
| 19 | NixOS 启动失败 | 无系统级 glibc | 安装 `nix-ld` 兼容层 |
| 20 | 性能问题 / 卡顿 | 需要定位 | macOS 用 Xcode Instruments（Time Profiler）采样；Linux 用 `perf record -g --call-graph dwarf -p <pid>` 抓火焰图（详见官方文档） |

通用排障手段：命令面板 `zed::About` 看版本、`zed::CopySystemSpecsIntoClipboard` 复制系统规格、`zed::OpenLog` / `zed::RevealLogInFileManager` 查看日志（macOS `~/Library/Logs/Zed/Zed.log`，Windows `%LOCALAPPDATA%\Zed\logs\Zed.log`，Linux `~/.local/share/zed/logs/Zed.log`）；命令行 `zed --system-specs`、`ZED_LOG=wgpu=info zed --foreground .` 抓 GPU 相关日志。

## 十、升级、回滚与卸载

### 10.1 版本查看

```sh
zed --version                       # CLI 查版本
# 或编辑器内命令面板执行 zed::About
zed --system-specs                  # 版本 + 系统规格

# 安装脚本指定版本
curl -f https://zed.dev/install.sh | ZED_VERSION=0.216.0 sh

# Homebrew：安装历史 cask 版本或改用 zed@preview
brew install --cask zed@preview

# 脚本安装（macOS/Linux）
zed --uninstall       # 交互询问是否保留配置
# 或绝对路径
$HOME/.local/zed.app/bin/zed --uninstall

# 包管理器
brew uninstall --cask zed
winget uninstall ZedIndustries.Zed
sudo pacman -R zed
flatpak uninstall dev.zed.Zed

# 残留清理（按需，会丢失设置/会话/扩展）
rm -rf ~/.config/zed              # 设置与 keymap
rm -rf ~/.local/share/zed         # 日志、db、扩展（Linux）
rm -rf ~/Library/Logs/Zed ~/Library/Application\ Support/Zed   # macOS
rm -rf "$LOCALAPPDATA/Zed" "$APPDATA/Zed"                      # Windows
rm -rf ~/.zed_server              # 远端 server（在各远程主机上执行）

# 安装
curl -f https://zed.dev/install.sh | sh                       # Linux/macOS 脚本安装
curl -f https://zed.dev/install.sh | ZED_CHANNEL=preview sh   # preview 渠道
curl -f https://zed.dev/install.sh | ZED_VERSION=0.216.0 sh   # 指定版本
brew install --cask zed                                       # macOS
winget install -e --id ZedIndustries.Zed                      # Windows
script/linux && ./script/install-linux                        # 源码构建安装（Linux）

# CLI
zed .                          # 打开目录
zed ssh://user@host/path       # SSH 远程项目
zed --foreground .             # 前台调试
zed --system-specs             # 系统规格
zed --version                  # 版本
zed --uninstall                # 卸载

# AI 环境变量
export ANTHROPIC_API_KEY=...   # 或 OpenAI/DEEPSEEK/OPENROUTER/GEMINI/XAI/OLLAMA/..._API_KEY

# 常用排障命令
vkcube                                          # Vulkan 自检（Linux）
dxdiag                                          # DirectX 自检（Windows）
sudo sysctl fs.inotify.max_user_watches=64000   # inotify 上限
GPUI_X11_SCALE_FACTOR=1.5 zed                   # X11 缩放
ZED_LOG=wgpu=info zed --foreground .            # GPU 日志
tail -f ~/.local/share/zed/logs/Zed.log         # 跟踪日志

# 源码构建
cargo run                  # debug 运行
cargo run -p cli           # 运行 CLI
cargo test --workspace     # 测试
./script/install-linux     # 安装本地构建