第6课：错误处理、调试与部署可靠的 Workflow

imgimgimgimgimg
首先完成“第5课：Webhook 与事件驱动集成”即可解锁本课程。转到上一课

简介

即使是设计得再好的 Workflow，最终也会遇到 API 调用失败、payload 格式异常或超时等问题。在生产环境中，这些失败必须被捕获、记录并妥善处理——既不能悄无声息地忽略，也不能任由整个执行崩溃。本课将围绕可靠 n8n Workflow 的三大支柱展开：结构化的错误处理、通过执行日志进行调试，以及一套可应用于任何集成的上线前检查清单。

n8n 中的错误分支

n8n 提供两种主要的错误捕获机制：Error Trigger 节点和节点级错误输出。

Error Trigger 节点是 Workflow 级别的 catch。你需要新建一个 Workflow，将其唯一的 trigger 设为 Error Trigger 节点，然后通过 Settings > Error Workflow 将主 Workflow 指向它。每当主 Workflow 中任意节点抛出未被捕获的错误时，n8n 会自动启动该错误 Workflow，并传入包含 Workflow 名称、失败节点、错误信息以及完整执行 ID 的 payload。

json
{
  "execution": {
    "id": "1042",
    "url": "https://your-n8n-instance/execution/1042",
    "retryOf": null,
    "error": {
      "message": "Request failed with status code 429",
      "stack": "..."
    },
    "lastNodeExecuted": "HTTP Request",
    "mode": "webhook"
  },
  "workflow": {
    "id": "7",
    "name": "Sync CRM Contacts"
  }
}

在错误 Workflow 内部，你可以将该 payload 路由到 Slack、PagerDuty、邮件节点或数据库写入——由你团队的监控方式决定。

如果需要更精细的控制，可以在单个节点上启用 "Continue on Fail" 或激活节点级错误分支（HTTP Request、Code 以及大多数集成节点均支持），此时节点会暴露一个次级输出 pin。将其连接到下游节点，即可就地处理失败而不中断整个 Workflow。当批量中某一项失败需要被记录并跳过（而不是中止全部任务）时，这是正确的处理模式。

流程图：主 Workflow 节点分支为成功输出和错误输出，错误分支路由至 Slack 通知节点和数据库日志节点

使用执行日志追踪失败

每一次 n8n 执行——无论成功还是失败——都会被存储在 Executions 面板中。打开任意一次执行，你都可以查看每个节点精确的输入与输出数据，这使得追踪失败变得直接明了。

实际的调试循环如下：运行 Workflow，打开失败的那次执行，点击红色节点，查看 Output 选项卡。错误信息以及引发该错误的输入数据都会显示在该处。对于 HTTP 调用，你还可以看到原始的响应状态码和响应体，这通常比通用的错误字符串更具参考价值。

当内置面板不够用时——例如需要检查中间转换过程——可以插入一个临时的 Code 节点，仅做一件事：记录其输入数据：

javascript
console.log(JSON.stringify($input.all(), null, 2));
return $input.all();

n8n 会在该节点的执行详情中显示 console.log 的输出，因此你可以读取数据链中该位置的精确结构。部署前请删除该节点。

对于由 Webhook 触发的 Workflow，使用 "Listen for Test Event" 按钮捕获真实的传入 payload，并在开发过程中反复重放。这样可以避免每次迭代都要重新触发外部系统。

应用重试与超时设置

外部 API 会出现临时性故障。与其在 Code 节点中手写重试逻辑，不如在节点层面进行配置。在任意 HTTP Request 节点上，打开节点设置，设置 Max Retries（通常为 2–3 次）和 Retry Interval。n8n 会在遇到 5xx 响应和网络错误时自动退避并重试。

务必设置明确的 Timeout 值。默认情况下无超时，这意味着上游服务挂起时会无限期阻塞执行线程。10 000 到 30 000 毫秒之间的数值通常足以覆盖大多数 REST API。

json
{
  "options": {
    "timeout": 15000,
    "retry": {
      "maxTries": 3,
      "waitBetweenTries": 2000
    }
  }
}

该 JSON 表示的是你在 HTTP Request 节点 UI 中配置的 options 对象——并非手写内容，但在以 JSON 文件导出 Workflow 并进行版本管理时，理解其底层结构是很有用的。

上线前检查清单

在生产环境中启用任何 Workflow 之前，请逐项核对以下检查内容。

首先，将所有硬编码的凭证和 URL 替换为 n8n Credentials 或通过 $env 对象访问的环境变量。Secrets 绝不应以明文字符串的形式出现在节点参数中。

其次，确认所有外部调用都已设置超时，并在适当时设置重试参数。

第三，通过 Settings 将一个 Error Workflow 连接到生产 Workflow。通过临时添加一个故意抛出错误的 Code 节点来测试它：

javascript
throw new Error('Test error — remove before deploy');

确认你的 Slack 频道或告警系统收到了通知，然后删除测试节点。

第四，复核执行模式。由 schedule 或 Webhook 触发的 Workflow 应启用 "Save Execution Progress"，以避免在崩溃时丢失部分进度。

第五，限制存储内容。如果该 Workflow 处理个人数据，请根据你的数据保留策略，将 "Save Data Error Execution" 和 "Save Data Success Execution" 设置为 "Latest only" 或禁用。

清单流程图：5 个连续的上线前步骤——凭证检查、超时配置、错误 Workflow 测试、执行模式复核、数据保留设置

总结

生产级的 n8n Workflow 依赖三个习惯：使用 Error Trigger 或就地错误分支显式路由失败，而非让其消失；利用 Executions 面板和 console.log 在数据链中的任意位置检查数据；以及遵循一套涵盖凭证、超时、告警和数据保留的标准化上线前检查清单。这些实践前期投入的时间不多，却能消除你在凌晨两点本该进行的大部分调试工作。

课后练习

课程检查点

巩固所学知识，获取作业反馈。

0/1
已回答 · 0/1