第 4 章

调试与错误处理

Ch04 调试与错误处理

一个工作流在开发阶段能跑通，不代表生产环境永远稳定。网络超时、API 限速、数据格式异常……这些问题随时可能中断你精心设计的自动化流程。本章系统讲解 n8n 的调试工具链和错误处理策略，让你的工作流具备生产级健壮性。

执行日志面板：看清数据在节点间的流动

n8n 最强大的调试工具是执行日志面板。每次工作流执行后，点击任意节点都能看到该节点的输入数据（Input）和输出数据（Output），精确到每一个 JSON 字段。

使用技巧：

Schema 视图：默认展示数据的键值对结构，适合快速查看字段名和值
JSON 视图：切换到原始 JSON 视图，适合复制数据或检查嵌套结构
Table 视图：以表格形式展示多条 items，适合对比不同条目的字段
Binary 视图：查看文件节点（如读取 PDF、下载图片）的二进制数据

技巧： 在执行日志中点击某个字段的值，可以直接复制该值。对于需要在表达式中引用的复杂路径（如 data.items[0].price），可以先在执行日志中找到数据，再手动构建表达式。

Pin Data：固定测试数据，跳过费时的触发步骤

开发工作流时，每次调试都要等触发器触发、等 RSS 拉取数据、等 API 响应……这会让调试周期变得很长。**Pin Data（固定数据）**功能解决了这个问题。

使用方法：

先执行一次工作流，让某个节点产生真实的输出数据
在节点的 Output 面板顶部，点击 Pin 📌 按钮
被 Pin 的节点会显示图钉图标，下次执行时该节点会直接返回固定数据，而不重新执行
后续节点可以直接基于固定数据进行调试，无需重新触发上游

典型使用场景： 调试 OpenAI 节点时，Pin 住 RSS 节点和 Code 节点的输出。这样每次测试 OpenAI 节点的 prompt 时，不需要重新拉取 RSS 数据，既节省时间又节省 API 费用。

错误处理节点（Error Trigger）：全局错误捕获

n8n 提供了一个特殊的 Error Trigger 节点，专门用于捕获工作流执行失败的事件。通过它，你可以构建一个专用的"错误告警工作流"。

配置步骤：

创建一个新工作流，命名为 "Error Alert"
添加 Error Trigger 节点作为触发器，不需要任何配置
在后续节点中构建告警逻辑（发飞书/钉钉/邮件）
回到原始工作流，在工作流设置（Settings）中的 Error Workflow 字段选择 "Error Alert"

当原始工作流执行失败时，Error Trigger 会自动触发，并携带以下错误信息：

{
  "workflow": {
    "id": "abc123",
    "name": "Hacker News Daily Digest"
  },
  "execution": {
    "id": "exe456",
    "url": "https://your-n8n.com/execution/exe456",
    "error": {
      "message": "Request failed with status code 429",
      "description": "Too Many Requests - Rate limit exceeded",
      "context": {
        "node": { "name": "OpenAI Summary" }
      }
    },
    "lastNodeExecuted": "OpenAI Summary"
  }
}

利用这些数据，可以在飞书告警消息中直接包含出错工作流名称、出错节点、错误信息和执行记录链接，方便快速定位问题。

错误路由（Continue on Fail）：节点级容错

有时候，即使某个节点失败，你也希望工作流继续执行其他条目的处理，而不是整体中断。这时候可以使用节点设置中的 Continue on Fail 选项。

在节点配置面板的 Settings 标签下，可以找到以下错误处理选项：

选项	行为	适用场景
Stop And Error（默认）	节点出错时整个工作流停止	关键节点，不允许跳过错误
Continue	忽略当前 item 的错误，继续处理下一个	批量处理时某些 item 可能失败
Continue (using error output)	错误信息作为 item 数据输出，继续后续流程	需要记录哪些 item 失败了

注意： 选择 Continue 时要谨慎——如果某个关键节点失败了但被静默忽略，可能导致数据不一致或漏处理。建议配合日志记录，确保失败的 items 有迹可查。

重试机制配置

对于因为网络抖动或 API 临时限速导致的偶发性失败，自动重试是最简单的解决方案。在节点设置中可以配置：

Retry On Fail：开启重试
Max Tries：最大重试次数（建议 3-5 次）
Wait Between Tries：重试间隔（毫秒），建议设置指数退避

重试 vs 错误处理： 重试适合幂等操作（重复执行结果相同的操作），如 GET 请求、查询数据库。对于非幂等操作（如扣款、发送邮件），应避免盲目重试，否则可能导致重复操作。

告警通知：错误时自动发送飞书/邮件告警

结合 Error Trigger 和飞书 Webhook，可以构建一个完整的告警系统：

// 在 Error Trigger 和 HTTP Request 之间插入此 Code 节点
// 用于格式化错误信息，使告警消息更易读

const error = items[0].json;
const now = new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });

const alertMessage = {
  workflowName: error.workflow.name,
  errorNode: error.execution.error?.context?.node?.name || 'Unknown',
  errorMessage: error.execution.error?.message || 'Unknown error',
  executionUrl: error.execution.url,
  timestamp: now,
  // 根据错误类型给出修复建议
  suggestion: error.execution.error?.message?.includes('429')
    ? 'API 限速，请检查调用频率或升级 API 套餐'
    : error.execution.error?.message?.includes('401')
    ? '认证失败，请检查 API Key 是否过期'
    : '请检查执行记录详情',
};

return [{ json: alertMessage }];

最佳实践： 为每个生产工作流都配置错误通知工作流，并在告警消息中包含执行记录的直接链接（{{ $json.execution.url }}）。这样收到告警后只需一次点击就能看到完整的错误上下文，大幅缩短排查时间。

常见错误类型与排查策略

HTTP 401 / 403

API Key 错误或权限不足。检查 Credential 配置，确认 Key 未过期，确认 Key 有足够的 API 权限范围。

HTTP 429

API 限速。开启重试并设置等待时间，或在 Code 节点中添加延时（await new Promise(r => setTimeout(r, 1000))），或升级 API 套餐。

HTTP 500 / 502

目标服务器内部错误。通常是临时性问题，开启重试即可。如果持续出现，检查目标服务的状态页面。

Expression Error

表达式引用了不存在的字段。检查上游节点的实际输出结构，用 Optional Chaining（?.）避免空值错误，如 {{ $json.user?.name }}。

Timeout Error

HTTP Request 超时。在节点设置中增大 Timeout 值，或优化目标 API 的响应速度。

JSON Parse Error

响应体不是合法 JSON。检查 HTTP Request 的 Response Format 设置，可能需要改为 Text 后手动解析。

本章评分

4.5 / 5 (68 评分)