n8n-debugging

n8n 调试

出问题时，原因几乎总是：

1. 参数配置错误（值错误、类型错误、字段缺失）。
2. 假设过时（版本不同，行为与你记忆中的不同）。
3. 路径配置错误或连接错误（输出索引错误、合并输入错误、缺少连线、IF/Switch 连到了错误分支）。
4. 上游数据被剥离（某个中间节点用自己的输出替换了 $json，导致下游的 $json.x 解析为 null，尽管“它本该在那里”）。修复方法：按名称引用稳定的上游节点（$('Earlier Node').item.json.x）。
5. 项目上下文丢失（经过 Aggregate、Execute Once 或 Split Out 流程后，n8n 无法确定性地配对 .item 引用，错误信息类似“表达式正在引用……多个匹配项目”）。修复方法：使用 Merge 节点重新建立上下文；使用 $input.all().find(...) 进行显式查找；或者重新设计，保持项目对应关系稳定（例如拆分为无状态子工作流）。
6. 逻辑错误（连线和参数都正确，但工作流执行了错误操作，与代码中的逻辑错误相同）。
7. 真正的 Bug（罕见，但确实存在）。

系统地诊断：先做成本低的检查，只有这些检查无法解决问题时才深入调查。

不容妥协的原则

相信用户。“这不好用”意味着某些行为没有达到用户的预期，即使他们对症状的描述不够准确。不要用“它应该能用”或“你确定自己做了 X 吗？”来搪塞。先调查：用户描述的是真实的预期行为，执行数据和源代码反映的是真实的实际行为。找不到原因时，“我还不知道”胜过听起来合理的编造。

首选排查方式（按原因匹配低成本检查）

按可能性顺序，将原因与低成本检查对应起来：

1. 参数配置错误 → 通过 get_node_types 重新获取信息，与 get_workflow_details 对比，查找类型、值或缺失字段不匹配的情况。对出错节点单独运行 validate_node_config 会直接返回各参数的错误；对于结构深层或有条件的节点，这比逐一查看差异更快。

2. 假设过时 → 询问 n8n 版本，询问用户上次更新 skills 插件的时间；如果行为与技能说明相矛盾，则怀疑存在偏差。

3. 路径配置错误或连接错误 → 通过 get_workflow_details 检查 connections 对象。若 Merge 输入不匹配，请参阅 n8n-node-configuration 中的 references/MERGE_NODE.md。

4. 上游数据被剥离 → 沿链路追踪 $json.x 引用，查找是否有节点用自己的输出替换了 json。常见问题节点：Aggregate、HTTP-binary、Extract from File、处于“Run for All Items”模式的 Code、分支 Merge。不限于这些：只要某个节点的输出结构不包含上游字段，它就可能导致此问题。

5. 项目上下文丢失 → 检查任何 Aggregate / Execute Once / Split Out 节点下游是否存在 .item 引用，并改用 $input.all().find(...) 或 Merge 锚点。

6. 逻辑错误 → 使用 get_execution 逐步追踪数据，并将每个节点的输出与预期进行比较。

7. 真正的 Bug → 接下来阅读 n8n 源代码，然后查看 GitHub issues，最后寻找变通方法。

对于外部 API 问题，应以上游服务的 API 文档（而不是 n8n 的封装）为准。必要时，获取 API 文档和 n8n 源代码进行调试。

分步排查

如果上述低成本检查无法立即找出原因，请按以下顺序逐步排查。

步骤 1：确认症状

询问：

• 用户预期是什么？
• 实际发生了什么？
• 错误消息的具体内容是什么？
• 上次正常工作是什么时候？此后有哪些变化？

将模糊的描述（“它坏了”）具体化（“邮件发送到了错误地址”或“工作流返回 500，响应正文为空”），问题就会变得容易处理。

步骤 2：检查执行记录

get_execution({ executionId: <execution_id>, workflowId: <workflow_id>, includeData: true })

检查：

• 哪个节点失败了？
• 它收到的输入是什么？
• 错误消息是什么？ 仔细阅读。错误消息通常会指向原因。

没有执行 ID？请用户重新运行。

第 3 步：重新获取工作流

get_workflow_details({ workflowId: <workflow_id> })

确认当前的实际状态。用户可能查看的是另一个工作流，或记得的是过时版本。

对比：

• 节点与用户的心智模型是否一致。
• 连接与意图是否一致：通过 get_workflow_details 获取信息，并将 connections 对象与 SDK 代码进行对比。
• 凭据是否符合预期（参见 n8n-credentials-and-security）。
• **上游字段被剥离的风险：**数据源与下游 $json.x 消费节点之间，是否有节点会用自身的输出替换 json？常见问题节点包括 HTTP-binary、Extract from File、Aggregate、处于 "Run for All Items" 模式的 Code，以及分支 Merge；但如果任何节点的输出结构不包含上游字段，它都可能造成这种问题。消费节点应通过名称引用源节点（$('Source Node').item.json.x），而非 $json。否则，该字段会静默地解析为 null。
• **项目上下文风险：**Aggregate / Execute Once / Split Out 后面是否有下游 .item 引用？n8n 可能无法确定性地配对项目。在以往的执行记录中，查找 "The expression is referencing... multiple matching items"。

第 4 步：重新获取节点类型

get_node_types([{ name: '<failed-node>', resource: '...', operation: '...' }])

对比实际参数结构与配置。常见不匹配包括：

• 缺少必需参数。
• 类型错误（例如字符串与数字）。
• 在 n8n 的 UI 类型下拉菜单中，object 和 array 是不同的类型（Set、IF、Switch、Filter，以及任何要求你选择类型的地方）。选择 object 不会接受数组值，反之亦然。在表达式中则是标准的 JS（数组确实是对象），因此只有这些 UI 类型选择项会遇到此问题。当 ={{ ... }} 表达式返回的容器形状与类型槽位不匹配时，请注意这一点。
• 设置了依赖参数，却未设置其父参数（例如，设置了 credentials，但 authentication !== 'none'；或设置了 query，但 operation === 'executeQuery'）。使用正确的区分参数重新调用 get_node_types。

如果手动对比结构与配置太繁琐（参数层级深、AI 工具子节点多，或条件分支多），可直接运行 validate_node_config。每个失败项都会返回 { path, message }。对于工具子节点，请设置 isToolNode: true。

第 5 步：使用固定数据测试

prepare_test_pin_data({ workflowId: '<id>' })
test_workflow({ workflowId: '<id>' })

受控输入可以将“工作流出错？”与“输入异常？”区分开来。如果固定数据有效，但真实输入失败，问题就在于对真实输入的处理。

如果固定数据也产生了错误输出，问题很可能出在逻辑上：逐个追踪节点的输出，并与预期进行对比。测试运行中的 get_execution 会提供每个步骤实际输出的数据，这是判断各节点行为的事实依据。

第 6 步：阅读 n8n 源代码

当所有检查都通过，但行为仍然似乎不对时：

github.com/n8n-io/n8n

• 内置节点位于 packages/nodes-base/nodes/<NodeName>。
• 执行逻辑位于 packages/cli/src/...。
• 工作流运行时位于 packages/core/src/...。

代码的实际行为就是事实。

参见 references/FETCHING_N8N_SOURCE.md。

步骤 7：排查双方是否存在版本漂移

如果步骤 1-6 都已确认无误，但行为仍不符合预期，那么最可能的剩余原因就是版本漂移。双方会各自独立漂移：

• 他们的 n8n 实例版本。 询问版本。（UI：Settings → About，或 GET /rest/settings。）在较旧的实例上，技能所假定的参数和工具可能不存在；在非常新的实例上，参数结构或工具名称可能已经变更。建议更新到最新的 n8n 版本；如果听说有修复，或问题是最近才出现的，则建议更新到最新的 beta 版本。
• 此技能插件的版本。 随着时间推移，这些技能会逐渐与 n8n 版本不一致。如果用户很久以前安装了该插件，建议在技能仓库中运行 git pull（或使用插件管理器的更新命令）。参见 README 的“Drift”部分。

版本漂移会表现为：get_node_types 中的参数结构不匹配、MCP 工具不存在或带有新参数、工具描述与技能中的说明相矛盾，以及实际行为偏离技能的描述。发现上述任何情况时，都要明确告知用户可能存在版本漂移：“这可能是你的 n8n 版本与这些技能之间存在版本漂移。能告诉我你的 n8n 版本，以及你上次更新这些技能的时间吗？”

如果更新双方后问题仍然存在，请继续执行步骤 8。

步骤 8：报告问题或采取变通方案

对于已确认的 bug：

• 让用户在 https://community.n8n.io 上提问
• 向用户清楚说明复现步骤。
• 查看 n8n GitHub issues。问题可能已经有人提交。
• 如果问题阻塞了工作，采用变通方案（更换节点或方法），并在工作流备注中说明。
• 如果修复正在进行中，请用 `` 标记变通方案

参考文件

文件	阅读时机
references/PARAMETER_VERIFICATION.md	参数可能配置错误，需要系统性地重新检查时
references/FETCHING_N8N_SOURCE.md	n8n 的行为与文档矛盾，需要查看实际代码时

反模式

反模式	问题所在	修正方法
“这应该能用，你确定自己正在执行 X 吗？”	否定用户的反馈，可能忽略真实问题	相信用户。进行调查。
不检查执行记录就重新运行	同样的失败出现两次，没有新信息	对失败的运行调用 get_execution，查看错误
行为与文档矛盾时仍假定文档准确	接受错误的认知模型	阅读源代码。行为才是事实
配置好的节点失败时，在 Code 节点中重新实现逻辑	掩盖 bug，没有解决根本原因	先诊断，确认 bug 后再采用变通方案
随机删除节点来二分排查	浪费时间	逐步检查 get_execution，直接找到失败的节点
要求用户重新截图，而不通过 MCP 检查	缓慢且容易出错	使用 get_workflow_details 和 get_execution
还没弄清问题原因，只是绕过 bug 却称其为“已修复”	bug 会以略有不同的形式再次出现	记录原因。如果采用变通方案，请用 `` 标记
未询问用户的 n8n 版本或上次更新技能的时间，就断定是“bug”	真正的原因通常是版本漂移；用户更新后，“bug”可能就消失了	报告前询问双方的版本信息。参见步骤 7。