n8n-debugging-official

n8n 调试

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

1. 参数配置错误（值错误、类型错误或缺少字段）。
2. 假设过时（版本不同，或行为与你记忆中的不同）。
3. 路径配置错误或连接错误（输出索引错误、Merge 输入错误、缺少连线，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-official 的 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_workflow_execution 追踪数据，比较每个节点的输出与预期。

7. 真正的 Bug → 依次查阅 n8n 源代码、GitHub issues，然后再寻找变通方案。

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

分步讲解

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

第 1 步：确认症状

询问：

• 他们预期会发生什么？
• 实际发生了什么？
• 错误消息的具体内容是什么？
• 上次正常运行是什么时候？此后有什么变化？

将模糊的问题（“出故障了”）具体化后，就更容易处理了（“邮件发到了错误的地址”或“工作流返回了正文为空的 500 错误”）。

第 2 步：检查执行情况

get_workflow_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-official）。
• 上游字段被剥离的风险： 数据源与下游 $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_workflow_pin_data({ workflowId: '<id>' })
test_workflow({ workflowId: '<id>' })

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

如果固定数据也会产生错误输出，那很可能是逻辑错误：逐个追踪每个节点的输出，并与预期结果进行比较。对测试运行调用 get_workflow_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 实例版本。 询问用户。（界面路径：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_workflow_execution，查看错误
行为与文档矛盾时仍假定文档准确	接受错误的心智模型	阅读源代码。行为才是事实
配置好的节点失败时，在 Code 节点中重新实现逻辑	掩盖 Bug，无法解决根本原因	先诊断；仅在确认 Bug 后才采用变通方案
随机删除节点进行二分排查	浪费时间	通过 get_workflow_execution 逐步检查，直接找到失败的节点
不通过 MCP 检查，而是让用户重新截图	速度慢且容易出错	使用 get_workflow_details 和 get_workflow_execution
还没弄清问题就绕过 Bug，却称问题已“修复”	Bug 会以略有不同的形式再次出现	记录原因。如果采用变通方案，请用 `` 标记
未询问用户的 n8n 版本或其上次更新技能的时间，就宣称这是“Bug”	真正原因往往是版本漂移，用户更新后“Bug”就会消失	报告问题前询问双方的版本。参阅第 7 步。