第3章 Zed 编辑器故障排查指南
本指南介绍了 Zed 的常见故障排查方法。有时你可以根据这些信息自行识别并解决问题；但更多时候，排查意味着收集正确的信息（如日志、性能剖析数据或复现步骤），以便我们诊断和修复问题。
注意：打开命令面板时，macOS 使用
cmd-shift-p，Windows 和 Linux 使用ctrl-shift-p。
获取 Zed 和系统信息
在报告问题或寻求帮助时，了解你的 Zed 版本和系统规格非常有用。你可以通过命令面板中的以下操作获取这些信息：
- {#action zed::About}：查找你的 Zed 版本号
- {#action zed::CopySystemSpecsIntoClipboard}：将 Zed 版本号、操作系统版本和硬件规格复制到剪贴板
- {#action zed::CopyInstalledExtensionsIntoClipboard}：将你已安装的扩展列表及其版本复制到剪贴板
Zed 日志
在排查 Zed 中的任何问题时，Zed 日志通常是一个好的切入点，其中可能包含问题所在线索。你可以运行命令面板中的 {#action zed::OpenLog} 操作，查看日志最近 1000 行。若想查看完整文件，可通过命令面板中的 {#action zed::RevealLogInFileManager} 在操作系统的原生文件管理器中显示该文件。
Zed 日志在各自的操作系统中位于以下位置：
- macOS：
~/Library/Logs/Zed/Zed.log - Windows：
C:\Users\YOU\AppData\Local\Zed\logs\Zed.log - Linux：
~/.local/share/zed/logs/Zed.log或$XDG_DATA_HOME
注意：在某些情况下（例如 开发 Zed 扩展 时），实时监听日志会很有用。 示例：
tail -f ~/Library/Logs/Zed/Zed.log
日志中可能包含足够的上下文信息，帮助你自行调试问题；或者你发现的特定错误在提交 GitHub issue 或在我们 Discord 服务器 中与 Zed 团队沟通时很有帮助。
性能问题（Profiling）
如果你在使用 Zed 时遇到性能问题（卡顿、无响应等），在 issue 中附上性能分析报告（profile）能帮助我们更快定位卡在哪里。
macOS
Xcode Instruments（随 Xcode 一并安装）是 macOS 上的标准性能分析工具。
- 在 Zed 运行的状态下打开 Instruments
- 选择
Time Profiler作为分析模板
- 在
Time Profiler配置中，将目标设为正在运行的 Zed 进程 - 开始录制
- 在 Zed 中执行引发性能问题的操作
- 停止录制
- 保存 trace 文件
- 将 trace 文件压缩为 zip 包
- 提交 GitHub issue 并附上该 zip 包
启动与工作区问题
Zed 会在本地创建 SQLite 数据库来持久化工作区和项目相关的数据。这些数据库存储的内容包括：项目中打开的标签页和面板、每个打开文件的滚动位置、你打开过的所有项目列表（用于最近项目选择器）等等。你可以在以下位置找到这些数据库：
- macOS：
~/Library/Application Support/Zed/db - Linux 和 FreeBSD：
~/.local/share/zed/db（或位于XDG_DATA_HOME或FLATPAK_XDG_DATA_HOME下） - Windows：
%LOCALAPPDATA%\Zed\db
这些数据库的命名格式为 0-<zed_channel>：
- Stable：
0-stable - Preview：
0-preview - Nightly：
0-nightly - Dev：
0-dev
尽管罕见，但我们确实遇到过几次工作区数据库损坏导致 Zed 无法启动的情况。如果你遇到启动问题，可以暂时将数据库从其原位置移走，然后尝试再次启动 Zed，以判断问题是否源于工作区数据库。
注意：移动工作区数据库后，Zed 会创建一个全新的数据库。你的最近项目、打开的标签页等设置将恢复出厂状态。
如果重新生成数据库后问题依旧，请 提交 issue。
语言服务器问题
如果你遇到与 language server 相关的问题，如诊断信息过时或跳转到定义失败，通常可以通过命令面板中的 {#action editor::RestartLanguageServer} 重启语言服务器来解决。
Agent 错误信息
"Max tokens reached"
当 agent 的响应超过模型的最大 token 限制时，会看到此错误。触发场景包括：
- Agent 生成了极长的响应
- 对话上下文加响应内容超出了模型容量
- 工具输出体积过大，占用了可用的 token 预算
解决方法：
- 开启新线程以缩减上下文大小
- 在 AI 设置中更换 token 上限更大的模型
- 将请求拆分为更小、更聚焦的任务
- 使用线程控制功能清除工具输出或历史消息
不同模型的 token 上限各不相同，请查阅模型服务商的文档了解具体限制。
