引言
写代码的人，都绕不开一个环节：调试。
你可能有过这样的经历：一个看似简单的bug，你花了半天时间定位问题。你可能也有过另一种经历：调试工具太复杂，配置了一小时还没跑起来。这两种体验的背后，藏着同一个张力：工具应该让事情变简单，还是应该提供足够的控制力？
这个问题没有标准答案。但它让我想起马奇在《经验的疆界》里说过的一句话：经验可能的确是最好的老师，但她不是一个特别好的老师。
借用这句话的模式，我想说：工具可能的确是最好的助手，但它不是一个特别好的助手。
今天，我想聊聊Zed的调试配置。具体来说，我想聊聊怎么写好一个.zed/debug.json文件，以及在这个过程中，我们如何理解「简单」与「复杂」的辩证关系。
一、问题的起源
事情是这样的。
我最近开始用Zed写Go。Zed很快，界面很现代，代码补全很流畅。但当我需要调试代码的时候，我发现了一个问题：我不太会配置Zed的调试。
不是因为Zed的文档写得不好，而是因为「调试」这个概念本身就包含了太多层次。启动调试器、设置断点、传递参数、管理环境变量、关联构建流程……每一个步骤都可以展开成无数的选择。
这就让我想起了一个更根本的问题：当我们在配置调试工具时，我们到底在配置什么？
表面上看，我们是在告诉IDE「如何启动程序」。但实际上，我们是在定义「什么是调试这个行为」。不同的配置方式，代表了对调试的不同理解，也就会产生不同的调试体验。
Zed的debug.json，就是这个理解的具体表达。
二、一层嵌套的悖论
在深入细节之前，我想先提出一个观察。
Zed的调试配置，看起来很简单——就是一个JSON数组，每个元素是一个调试任务。每个任务有一些必填字段和一些可选字段。
但如果你仔细看，你会发现这个「简单」里面嵌套着复杂。
以Go语言为例。除了通用的label、adapter、request字段，Go还需要配置mode和buildFlags。mode决定了调试器以什么模式运行——是debug模式（调试源码）还是test模式（调试测试）？buildFlags决定了编译时的额外参数——要不要加构建标签？要不要设置环境变量？
这还没完。如果你希望调试器能自动完成「先构建再启动」的流程，你还需要了解build字段的两种写法：内联定义和引用tasks.json。
每一层都有选择，每一层都可能影响最终的调试体验。
这里出现了一个典型的马奇式悖论：配置越详细，调试越精准；但配置越复杂，学习的门槛越高。
好的工具设计，应该在这两者之间找到平衡。
三、简单与复杂的辩证
让我具体看看Zed是怎么处理这个问题的。
Zed有一个很聪明的设计：零配置支持。
如果你只是调试一个Go的main包，或者调试当前光标所在的测试函数，你可以完全不创建debug.json文件，直接按F4，Zed会自动识别并启动调试。
这个设计太重要了。它意味着：对于最简单的场景，复杂的技术细节被完全隐藏了。你不需要知道什么是Delve，不需要知道mode参数怎么设置，甚至不需要知道debug.json是什么。Zed帮你做了所有决策。
但当你需要更多控制的时候，复杂性就出现了。你想调试一个特定的二进制文件？你想传递特定的命令行参数？你想在调试前自动执行构建？这时，你必须深入debug.json的字段细节。
这就是我说的「一层嵌套的悖论」的体现：简单和复杂不是对立的两极，而是嵌套在一起的两个层次。简单是复杂的特例，复杂是简单的延伸。
马奇在讨论组织时说过：结构是历史的产物，而不是理性设计的产物。Zed的调试配置设计也是如此。它不是先设计好一个完美的层次体系，然后让用户去适应；而是先提供一个最简单的默认，然后让需要更多控制的用户自己去添加复杂性。
这种「先简单，后复杂」的设计哲学，可能比「先复杂，后简化」更符合人类的学习规律。
四、字段的层级
现在，让我们具体看看debug.json的字段设计。
我觉得可以从两个维度来理解这些字段：
第一个维度是「控制力」。有些字段控制的是「宏观」的东西——比如label决定了这个配置在菜单里显示什么，adapter决定了用什么调试器。有些字段控制的是「微观」的东西——比如args决定了传递给程序的命令行参数，env决定了环境变量。
第二个维度是「频率」。有些字段是每次调试都会用到的，比如program和request。有些字段是偶尔才需要配置的，比如buildFlags和mode。
如果我们把这两个维度结合起来，我们可以得到一个简单的分类：
| 维度 | 高频 | 低频 |
|---|---|---|
| 宏观 | label, adapter | request, cwd |
| 微观 | args, env | build, buildFlags |
这个分类有什么用？它可以帮助我们决定在哪里投入学习精力。对于高频字段，我们应该理解它们的含义和常用取值。对于低频字段，我们只需要知道「有这个功能」，等用到的时候再查文档。
这是一种「有限理性」的学习策略——不是追求对所有字段的全面掌握，而是把注意力集中在最有价值的部分。
五、一个Go示例
说了这么多，让我们回到具体场景。
假设你有一个Go项目，结构如下：
myproject/
├── cmd/
│ └── server/
│ └── main.go
├── internal/
│ └── handler.go
└── go.mod
你想调试server/main.go。最简单的配置是这样的：
[
{
"label": "Debug Server",
"adapter": "Delve",
"request": "launch",
"mode": "debug",
"program": "./cmd/server"
}
]
这个配置足够简单，但它能满足你的需求吗？可能不够。
假设你的server需要传递一些参数，比如-port=8080。你需要添加args字段：
[
{
"label": "Debug Server",
"adapter": "Delve",
"request": "launch",
"mode": "debug",
"program": "./cmd/server",
"args": ["-port=8080"]
}
]
配置好之后，可以使用快捷键f4来进行debug
在编辑器下方就会输出运行日志
假设你想在调试前自动构建，而不是手动执行
go build。你需要添加build字段：
[
{
"label": "Debug Server with Build",
"adapter": "Delve",
"request": "launch",
"mode": "exec",
"program": "${ZED_WORKTREE_ROOT}/bin/server",
"build": {
"command": "go",
"args": ["build", "-o", "bin/server", "./cmd/server"]
}
}
]
注意这里mode变成了"exec"，program指向编译好的二进制文件。这是一种不同的调试模式——不是让Delve直接启动源码调试，而是让Delve控制一个已经编译好的进程。
再进一步，假设你有很多构建任务，想复用tasks.json中的定义。你可以简化build字段：
// .zed/tasks.json
[
{
"label": "Build Server",
"command": "go",
"args": ["build", "-o", "bin/server", "./cmd/server"]
}
]
// .zed/debug.json
[
{
"label": "Debug Prebuilt Server",
"adapter": "Delve",
"request": "launch",
"mode": "exec",
"program": "${ZED_WORKTREE_ROOT}/bin/server",
"build": "Build Server"
}
]
这种引用的方式，让构建和调试的配置可以分开管理，提供了更好的模块性。
六、我的一点观察
写到这里，我想停下来发表一个观点。
debug.json的配置，表面上是一个技术问题，但它的本质是一个认知负荷的问题。
每增加一个字段，开发者就需要多理解一个概念。args、env、cwd、buildFlags……这些字段加起来，构成了一个需要学习的「配置语言」。这个语言有自己的语法、语义和惯用法。
好的配置设计，应该让这个语言尽可能简洁。但简洁是有代价的——太简洁的配置表达能力有限，无法满足复杂场景的需求。
这是一个典型的「够好」问题。在有限理性的框架下，我们不是在追求「最优的配置语言」，而是在「足够的表达力」和「足够的学习成本」之间找到平衡。
Zed的策略是：先用零配置覆盖最常见的场景，然后用可选字段满足高级需求。这个策略不完美，但它体现了对「简单与复杂嵌套」这一事实的尊重。
马奇在讨论经验时说：经验可能的确是最好的老师，但她不是一个特别好的老师。借用这句话，我可以说：零配置可能的确是最好的默认，但它不是一个特别好的默认。
七、变量与灵活性
在结束之前，我想特别提一下Zed提供的变量系统。
$ZED_WORKTREE_ROOT、$ZED_FILE、$ZED_SYMBOL……这些变量看起来只是占位符，但它们实际上解决了一个很重要的问题：配置的跨环境可移植性。
如果你在配置里硬编码了/Users/yourname/project/bin/server，那这个配置就只能在你的机器上工作。换一台电脑，或者换一个项目目录，就会失效。
通过使用变量，你可以写出「一次编写，到处运行」的配置。当然，这里有个前提：变量系统本身需要被正确理解。
这个问题的背后，是一个更普遍的设计原则：好的配置应该对环境变化有鲁棒性，而变量是实现鲁棒性的一种方式。
八、总结
回到文章开头的问题：我们在配置调试工具时，我们到底在配置什么？
我现在觉得，我们配置的不只是「如何启动程序」，而是我们对「调试这个行为」的理解。每一行配置，都是这个理解的具体表达。
Zed的debug.json设计，帮我验证了一个想法：简单和复杂不是对立的两极，而是嵌套在一起的两个层次。
对于初学者，零配置已经足够让他们开始调试。对于进阶用户，debug.json的丰富字段提供了足够的控制力。这是一种「分层」的解决方案，不是非此即彼的二元选择。
最后，我想用马奇的一句话来收尾。那句话是关于「智慧」的：智慧既需要适应环境，又需要诠释经验。
调试也是如此。我们既需要工具能适应我们的调试需求（零配置、自动识别），又需要我们能诠释调试过程背后的逻辑（理解每个字段的含义，理解配置与行为的对应关系）。
学会配置debug.json，可能不是最重要的。重要的是通过这个过程，理解「简单」与「复杂」是如何相互嵌套、相互塑造的。
附录：Go调试完整配置示例
// .zed/debug.json
[
{
"label": "Debug Main Server",
"adapter": "Delve",
"request": "launch",
"mode": "debug",
"program": "./cmd/server",
"args": ["-env=dev"],
"cwd": "${ZED_WORKTREE_ROOT}"
},
{
"label": "Debug Current Test",
"adapter": "Delve",
"request": "launch",
"mode": "test",
"program": ".",
"args": ["-test.run", "${ZED_SYMBOL}"]
},
{
"label": "Debug with Build",
"adapter": "Delve",
"request": "launch",
"mode": "exec",
"program": "${ZED_WORKTREE_ROOT}/bin/server",
"build": {
"command": "go",
"args": ["build", "-o", "bin/server", "-tags=jsoniter", "./cmd/server"]
}
}
]
按F4，选择一个配置，开始调试。