n8n 工作流深度审查清单用 n8n-mcp 对既有工作流做严重性分级审计【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读validate_node/validate_workflow能捕获 schema 与结构错误却挡不住那些验证通过、运行无误、结果悄悄出错的静默问题。本篇基于 n8n-mcp 仓库中 REVIEW_CHECKLIST.md 整理的审查清单讲解如何对已存在的n8n 工作流无论自己的还是他人移交的执行一次严重性分级的 JSON 级审计覆盖安全漏洞、反模式、看似合法实则断路的连接与缺失的错误路径并给出每个问题的定位方法、修复方向和对应的规范技能文档。这份清单与边建边验证的根本区别n8n 的验证技能SKILL.md描述了一条配置 →validate_node→ 读错误 → 修复 → 再验证的迭代回路专门捕获进行中工作的 schema 与形状错误而 REVIEW_CHECKLIST 面向已经存在的工作流——它早已通过validate_workflow你要找的正是验证器放过的静默问题反模式antipatterns安全漏洞security holes合法但断路的连接broken-but-valid connections缺失的错误路径missing error paths清单内置一个典型判断validate_workflow现在会把错误输出已启用但未接线这类问题以警告形式暴露n8n-mcp ≥ 2.63.0但它不会把valid置为false因此这类问题仍然属于人工审查项而非自动拦截项。如何使用三步走先拉取工作流再逐项核对。用n8n_get_workflow({ id })拿到真实 JSON从清单顶部向下逐条判断是否适用。n8n_get_workflow支持多种模式详见 n8n-get-workflow.tsstructure只看节点与连接拓扑适合快速读图full默认草稿 元数据需要看参数时使用filterednodeNames只读单个重节点如很长的 Code 节点避免大工作流整包拉取时在客户端被截断对应 issue #101details追加执行统计成功/失败次数、最近执行时间active读取真正在运行的生产图draft/publish 分离模型下与草稿可能不一致minimal只取 id、name、active、tags最快。逐条判定。每条检查项对照实际 JSON 决定是否适用。按严重性分组汇报。每个发现指向负责为什么与怎么修的规范技能文档。你审查的是 JSON不是源码。n8n_get_workflow返回的节点带有parameters、credentials以及nodes-base.httpRequest这类type字符串外加一张connections图。汇报时要用 JSON 语言措辞例如节点Route order缺少parameters.options.fallbackOutput未匹配的条目会被静默丢弃。清单中所有裸写的NODE_FAMILY_GOTCHAS.md引用均指向 n8n-node-configuration/NODE_FAMILY_GOTCHAS.md。严重性分级模型严重性含义行动MUST FIX阻断发布的硬伤安全漏洞、断路连接、生产级破坏性 bug若工作流处于激活状态先停止修复后再重新启用SHOULD FIX真实问题反模式、生产路径上缺失错误处理、契约被破坏在下次变更时修复NICE TO HAVE打磨项命名、描述、可读性顺带清理审查代理不得未经用户确认就自动修复 MUST FIX 项——安全与连接变更的爆炸半径很大。正确的做法是暴露发现、提出修复方案、等待用户批准。跨切面优先检查Cross-cutting first正式进入分级清单前先完成三项全局检查拉取工作流n8n_get_workflow({ id })让每条检查都跑在真实 JSON 上而非假设上。大工作流优先structure快速读图需要参数时用full读单个重节点用filterednodeNames。逻辑冒烟测试Logic smell test自上而下追踪一次 happy path。结构是否符合工作流声明的用途是否存在死代码、矛盾或不合时宜的东西只读流程里出现写节点、扇出分支没有接线、HTTP 调用指向无关域名→ 指向 n8n-workflow-patterns。记录触发类型及其是否激活严重性会随二者变化——webhook/API 或无人值守的调度需要手动运行不需要的错误路径带断路连接的激活工作流严重性更高。MUST FIX阻断发布的硬伤凭据与密钥Credentials and secrets节点文本字段中硬编码令牌 / API Key / 密码Bearer xxx、sk-...直接写进 HTTP header 值、query 参数或任意参数。凭据系统是唯一正确的存放位置。用n8n_manage_credentials检查/迁移。→ n8n-mcp-tools-expert凭据管理。该工具支持getSchema/create/get/update/delete/list全生命周期操作且建议任何创建动作前先getSchema确认字段见 n8n-manage-credentials.ts。Set 节点中存放密钥供后续{{ $json.token }}引用。无论怎么读取密钥都在工作流 JSON 里。→ n8n-mcp-tools-expertCode 节点内硬编码凭据。泄露面与文本字段相同。→ n8n-code-javascript / n8n-code-python反模式章节credentials块中残留占位符凭据 ID如id: REPLACE_ME。n8n 会对未知 ID 渲染一个永久禁用的选择器。真实 ID 未知时直接省略该块。→ n8n-node-configuration运行n8n_audit_instance可自动跨实例暴露硬编码密钥与未认证 webhook。→ n8n-validation-expert。该工具把 n8n 内置审计credentials / database / nodes / instance / filesystem 五类与自定义深度扫描hardcoded_secrets覆盖 50 种密钥模式、unauthenticated_webhooks、error_handling、data_retention合并输出带修复步骤的 Markdown 报告详见 n8n-audit-instance.ts。SQL / 查询注入SQL / query injection用户输入被插值进查询字符串。任何 DB 节点在parameters.query内出现{{ ... }}——n8n 会在驱动绑定参数之前把它替换进 SQL 文本因此这是注入向量。正确做法Postgres/MySQL 用$1, $2占位符 parameters.options.queryReplacementMongo 用对象过滤器。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase 段。底层原理详见该文档queryReplacement接受逗号分隔列表每段成为一个绑定参数{{ $json.email }},{{ $json.id }}→$1, $2值只经驱动绑定、永不接触 SQL 文本MySQL 节点同样用$1,$2queryReplacement非原生?节点会归一化到驱动。连接 bug合法但断路Connection bugs: valid but brokenMerge 接了 3 个来源但numberOfInputs仍是 2。第三个来源被静默丢弃。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdMerge 段。numberOfInputs默认 2画布上 3 条线中的第 3 条连到了不存在的输入槽修复为与线数一致后务必用n8n_get_workflow核对parameters.numberOfInputs与connections中源条目数一致。Merge 索引差一off-by-one。parameters.useDataOfInput是1 索引的对应 UI 的 Input 1/2/3而connections.source.main[idx]与其他数组一样是0 索引。翻译规则useDataOfInput: N由main[N-1]处的连接供数。错位时下游拿到的数据形状对、内容错看起来完全正常。唯一可靠的核验方式是用n8n_get_workflow读connections对象确认。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdMerge错误输出已启用但未接线或已接线但未启用。若parameters.onError是continueErrorOutput而节点的错误输出为空失败项被静默丢弃若节点接了错误分支但onError未设置分支不可达失败会中止整个工作流。validate_workflow自 n8n-mcp ≥ 2.63.0 起会把两者都标为警告但都不会翻转valid:false所以仍是审查项。按节点类型定位错误输出它是节点自然输出之后的最后一个main[]槽——单输出节点如 HTTP Request是main[1]但 IF 上是main[2]其main[1]是正常 false 分支Switch / Split In Batches 同理。不要把多输出节点上已接线的第二分支误认为未接线的错误输出。→ n8n-validation-expertSwitch没有兜底输出fallback。缺少parameters.options.fallbackOutput: extra时未匹配任何规则的条目被静默丢弃。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSwitch 段。修复示例设置options.fallbackOutput: extra并用options.renameFallbackOutput命名同时给每个规则输出命名接线后确认兜底分支通向真实去处日志、告警或 NoOp——启用了兜底却连到空处丢数据效果一样。Webhook API 工作流执行敏感操作的 webhook 使用parameters.authentication: none。敏感 变更状态、发送外部消息、触碰生产数据、触发付费动作。任何拿到 URL 的人都能触发。将authentication设为basicAuth/headerAuth并匹配对应凭据。→ n8n-workflow-patternswebhook、n8n-mcp-tools-expert凭据错误分支返回 HTTP 200。每个 Respond 节点的responseCode默认都是 200包括错误路径。调用方看到的成功与 body 中的失败自相矛盾——最坏的情况是调用方的错误处理永远不会触发。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhook。每个 Respond 分支都应显式设置responseCode4xx 表示调用方错误400 校验、401/403 鉴权、409 冲突、429 限流5xx 表示服务端错误。SHOULD FIX应在下次变更时修复Set 节点反模式Set 节点只喂 0 或 1 个下游消费者——最常见的反模式。删除它把表达式内联到消费者处。例外2 消费者共用一个非平凡派生值或子工作流的最终 Return 节点。→ n8n-expression-syntaxThe Set-node antipattern and branch convergenceSet 节点拼装邮件 / Slack 正文。在通信节点的 body 字段内联构建。→ n8n-expression-syntaxSet 节点在写节点前映射字段。直接在写节点的逐字段表达式槽内映射。→ n8n-node-configuration多个连续 Set 节点各定义一个字段。合并为一个或直接消除。→ n8n-expression-syntaxCode 节点反模式Code 节点做纯单条目整形.map/.filter/.find、字段改名、可选链。改用表达式或 Edit Fields 的 arrow-function IIFE——结果相同约快百倍更可读。→ n8n-code-javascripttransform gatekeeperCode 节点使用crypto.createHash/crypto.createHmac。改用原生 Crypto 节点nodes-base.crypto。反复出现的疏漏。→ n8n-code-javascriptCode 节点解析 XML / SOAP / RSS。用原生 XML 节点nodes-base.xml Edit Fields 做提取。→ n8n-code-javascriptCode Set 节点组合Set 建输入、Code 做变换。一个 Edit Fields arrow-function IIFE 两者兼做。→ n8n-code-javascript能用 JS 却用了 Python Code 节点。约 95% 的场景推荐 JSPython 留给其标准库强项regex、hashlib、statistics且仅当用户明确要求时。→ n8n-code-python表达式纪律Expression discipline分支繁多 / 多步工作流深处使用$json.x。改用$(Source Node).item.json.x以换取重构稳定性$json形式在插入中间节点或上下文被清空时会静默失效。→ n8n-expression-syntaxnon-negotiable分支汇合后下游仍用$json引用。最后触发的分支胜出结果不确定。在合并点插入 NoOpCombine Inputs并按名字引用它分支形状不一致时用 Set 归一化。→ n8n-expression-syntax用 DateTime 节点做日期运算 / 格式化。改用内联 Luxon 表达式DateTime.fromISO(...).toFormat(...)。→ n8n-expression-syntax任何表达式中使用$env.X。不工作运行时抛错。改用$vars.X付费套餐、Data Table 或凭据存密钥。→ n8n-expression-syntax.all().map()/filter()/reduce()聚合却未开executeOnce: true。每个输入条目都会重跑整次聚合——浪费算力且本应输出 1 条却输出 N 条相同结果。当.all()是以当前条目为键的逐条查找时不要开executeOnce。→ n8n-expression-syntaxSlack / 通信节点Block Kit 以裸数组传入。会静默以纯文本发出。包装为{{ { blocks: ... } }}。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSlack。注意按节点名引用来源$(Build Message).item.json.blocks而非$json且不要用 stringify-then-reparse 的杂交写法。线程回复发成了顶层消息——thread_ts未设置或位置错误。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSlack。字段位置在不同版本间有迁移旧文档放在otherOptions用get_node确认。operation 用了 UI 显示名send而非内部值post。用get_node确认。UI 标签与存储值经常分叉如 Gmail/Supabase 的 Get Many →getAll。→ n8n-node-configuration数据库select/ query 的无匹配路径接 IF但未设alwaysOutputData。无匹配 零条目 IF 永不触发。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase多步写入需要原子性却拆在多个节点。n8n 不存在跨节点事务合并进一个executeQuery并显式设置options.queryBatching: transaction不要依赖默认值它随节点版本漂移单查询与独立批处理是其他模式。Supabase 的 REST 层没有事务需要原子性时直连同一数据库的 Postgres 节点。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase写节点INSERT/UPDATE/DELETE后接期待其输出的节点却未设alwaysOutputData。写操作常返回 0 条而卡住整条链。→ n8n-node-configurationWebhook / Respond to Webhook请求/响应 API 却把responseMode留在onReceived。调用方永远看不到计算出的结果改用responseNode简单场景可用lastNode同步返回最后节点输出。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhook所有失败一律返回 500。映射状态码400 校验、401/403 鉴权、409 冲突、429 限流。→ n8n-node-configurationrespondWith: json的 body 用JSON.stringify(...)构建。会双重编码。在表达式模式直接传对象字面量{{ { status: ok, id: ... } }}让节点序列化一次。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhookwebhook 路径上的易失败节点HTTP/DB/API没有错误分支。失败会中止工作流调用方只收到 n8n 的通用错误。接onError: continueErrorOutput 一个 5xx Respond并验证接线。→ n8n-error-handling、n8n-workflow-patternswebhookHTTP Request认证头直接写进headerParameters而非凭据。改用 Bearer Auth / Header Auth 凭据。→ n8n-node-configuration、n8n-mcp-tools-expert同时通过headerParameters和凭据的 header auth 设置头。二者冲突。→ n8n-node-configuration网络调用节点HTTP/通信/DB/AI未开retryOnFail。瞬态 429 和抖动会表现为硬失败。瞬态失败处理暂时归入节点配置。→ n8n-node-configuration调度触发器业务关键调度没有显式工作流时区。夏令时和实例迁移会改变触发时刻。时区是工作流级设置Workflow Settings → Timezone规则内部没有时区字段可设cron 同时支持 5 字段Minute Hour DoM Month DoW与 6 字段带秒两种格式简单周期用 interval 模式更不易错。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSchedule调度触发的工作流不幂等。实例在触发时刻宕机该次运行直接被跳过没有补跑队列重启又可能重复触发。设计成跑两次结果一致必要时在工作流开头比对上次成功运行与预期节奏并追赶补跑。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSchedule结构与模式本可套用既有模式webhook、HTTP API、数据库、AI、调度、批处理的工作流没有可辨识结构。重塑为标准模式。→ n8n-workflow-patterns假设扇出分支并行执行。n8n 是顺序执行的真正的并发需要子工作流分发。子工作流专项技能尚待建立先记录该限制。→ n8n-workflow-patterns大条目量流程逐条干活而批处理/聚合能削减开销。→ n8n-workflow-patternsAI Agent / Code Tool若存在自定义 Code Tool 返回非字符串如[{json:{...}}]或使用$fromAI/$input/$helpers——这些在 Code Tool 沙箱中都不存在返回值必须是字符串。→ n8n-code-tool工具名称或描述过于泛化 / 为空。模型无法判断何时调用它描述本身就是 prompt 的一部分。用动词开头的具体名称。更深的 agent 指南尚待专项技能。→ n8n-code-toolNICE TO HAVE顺带打磨命名泛化节点名HTTP Request1、Set2、Postgres1。Fetch order details上的运行时失败能立刻定位断点HTTP Request3对运维人员毫无信息量。按节点在工作流中的职责重命名。→ n8n-workflow-patterns工作流名不是动词开头Send weekly customer report而非Customer report sender。句子大小写、无 emoji、无尾随版本号。→ n8n-workflow-patterns可读性工作流description为空或只有一行。写两句它做什么、为什么存在为什么是最容易丢失的部分。→ n8n-workflow-patternsCode 节点没有一行注释解释为何不用更简单的工具。→ n8n-code-javascript多行表达式未缩进 / 无注释。多数 n8n 用户不是程序员——像真实代码一样排版。→ n8n-expression-syntax汇报发现严重性优先、域分组、指向规范技能按严重性分组、域内再分组。每条发现给出受影响的节点、一句话描述、负责修复的规范技能。可复制的汇报模板原文摘录MUST FIX Security - Node Send webhook: bearer token typed into headerParameters value. - n8n-mcp-tools-expert (credentials) - Node Lookup user: {{ $json.email }} interpolated into parameters.query. - NODE_FAMILY_GOTCHAS.md (Database) Connections - Node Merge customer Stripe: 3 sources wired but parameters.numberOfInputs 2; third drops. - NODE_FAMILY_GOTCHAS.md (Merge) SHOULD FIX Set-node antipattern - Node Set customer_id: feeds one consumer; inline at Lookup customer. - n8n-expression-syntax ...与验证技能体系的协同这份清单不是孤立的。它与 n8n-validation-expert 中的验证回路互为补充回路负责建得对不对清单负责审得够不够。配套资源ERROR_CATALOG.md九类错误类型missing_required约占 45%、invalid_value约 28%、type_mismatch约 12% 等的完整示例与修复对照FALSE_POSITIVES.md哪些警告可接受n8n-mcp ≥ 2.63.0 后在源头修复了经典误报无需忽略的已知误报清单已不存在剩余警告要么是安全/弃用通知、要么是ai-friendly/strict下的最佳实践建议审查前可先用n8n_audit_instance做实例级扫描再用n8n_get_workflow逐工作流核对修复密钥类发现用n8n_manage_credentials结构类发现可考虑n8n_autofix_workflowapplyFixes: false先预览confidenceThreshold控制高/中/低置信度门槛fixTypes可限定 expression-format、typeversion-upgrade 等类型详见 n8n-autofix-workflow.ts。最后重申两条底线MUST FIX 项必须先经用户确认再动手安全与连接变更的爆炸半径大以及每个发现都要落在 JSON 术语上——让审查结果可复现、可定位、可修复。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 n8n 工作流深度审查清单：用 n8n-mcp 对既有工作流做严重性分级审计
n8n 工作流深度审查清单用 n8n-mcp 对既有工作流做严重性分级审计【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读validate_node/validate_workflow能捕获 schema 与结构错误却挡不住那些验证通过、运行无误、结果悄悄出错的静默问题。本篇基于 n8n-mcp 仓库中 REVIEW_CHECKLIST.md 整理的审查清单讲解如何对已存在的n8n 工作流无论自己的还是他人移交的执行一次严重性分级的 JSON 级审计覆盖安全漏洞、反模式、看似合法实则断路的连接与缺失的错误路径并给出每个问题的定位方法、修复方向和对应的规范技能文档。这份清单与边建边验证的根本区别n8n 的验证技能SKILL.md描述了一条配置 →validate_node→ 读错误 → 修复 → 再验证的迭代回路专门捕获进行中工作的 schema 与形状错误而 REVIEW_CHECKLIST 面向已经存在的工作流——它早已通过validate_workflow你要找的正是验证器放过的静默问题反模式antipatterns安全漏洞security holes合法但断路的连接broken-but-valid connections缺失的错误路径missing error paths清单内置一个典型判断validate_workflow现在会把错误输出已启用但未接线这类问题以警告形式暴露n8n-mcp ≥ 2.63.0但它不会把valid置为false因此这类问题仍然属于人工审查项而非自动拦截项。如何使用三步走先拉取工作流再逐项核对。用n8n_get_workflow({ id })拿到真实 JSON从清单顶部向下逐条判断是否适用。n8n_get_workflow支持多种模式详见 n8n-get-workflow.tsstructure只看节点与连接拓扑适合快速读图full默认草稿 元数据需要看参数时使用filterednodeNames只读单个重节点如很长的 Code 节点避免大工作流整包拉取时在客户端被截断对应 issue #101details追加执行统计成功/失败次数、最近执行时间active读取真正在运行的生产图draft/publish 分离模型下与草稿可能不一致minimal只取 id、name、active、tags最快。逐条判定。每条检查项对照实际 JSON 决定是否适用。按严重性分组汇报。每个发现指向负责为什么与怎么修的规范技能文档。你审查的是 JSON不是源码。n8n_get_workflow返回的节点带有parameters、credentials以及nodes-base.httpRequest这类type字符串外加一张connections图。汇报时要用 JSON 语言措辞例如节点Route order缺少parameters.options.fallbackOutput未匹配的条目会被静默丢弃。清单中所有裸写的NODE_FAMILY_GOTCHAS.md引用均指向 n8n-node-configuration/NODE_FAMILY_GOTCHAS.md。严重性分级模型严重性含义行动MUST FIX阻断发布的硬伤安全漏洞、断路连接、生产级破坏性 bug若工作流处于激活状态先停止修复后再重新启用SHOULD FIX真实问题反模式、生产路径上缺失错误处理、契约被破坏在下次变更时修复NICE TO HAVE打磨项命名、描述、可读性顺带清理审查代理不得未经用户确认就自动修复 MUST FIX 项——安全与连接变更的爆炸半径很大。正确的做法是暴露发现、提出修复方案、等待用户批准。跨切面优先检查Cross-cutting first正式进入分级清单前先完成三项全局检查拉取工作流n8n_get_workflow({ id })让每条检查都跑在真实 JSON 上而非假设上。大工作流优先structure快速读图需要参数时用full读单个重节点用filterednodeNames。逻辑冒烟测试Logic smell test自上而下追踪一次 happy path。结构是否符合工作流声明的用途是否存在死代码、矛盾或不合时宜的东西只读流程里出现写节点、扇出分支没有接线、HTTP 调用指向无关域名→ 指向 n8n-workflow-patterns。记录触发类型及其是否激活严重性会随二者变化——webhook/API 或无人值守的调度需要手动运行不需要的错误路径带断路连接的激活工作流严重性更高。MUST FIX阻断发布的硬伤凭据与密钥Credentials and secrets节点文本字段中硬编码令牌 / API Key / 密码Bearer xxx、sk-...直接写进 HTTP header 值、query 参数或任意参数。凭据系统是唯一正确的存放位置。用n8n_manage_credentials检查/迁移。→ n8n-mcp-tools-expert凭据管理。该工具支持getSchema/create/get/update/delete/list全生命周期操作且建议任何创建动作前先getSchema确认字段见 n8n-manage-credentials.ts。Set 节点中存放密钥供后续{{ $json.token }}引用。无论怎么读取密钥都在工作流 JSON 里。→ n8n-mcp-tools-expertCode 节点内硬编码凭据。泄露面与文本字段相同。→ n8n-code-javascript / n8n-code-python反模式章节credentials块中残留占位符凭据 ID如id: REPLACE_ME。n8n 会对未知 ID 渲染一个永久禁用的选择器。真实 ID 未知时直接省略该块。→ n8n-node-configuration运行n8n_audit_instance可自动跨实例暴露硬编码密钥与未认证 webhook。→ n8n-validation-expert。该工具把 n8n 内置审计credentials / database / nodes / instance / filesystem 五类与自定义深度扫描hardcoded_secrets覆盖 50 种密钥模式、unauthenticated_webhooks、error_handling、data_retention合并输出带修复步骤的 Markdown 报告详见 n8n-audit-instance.ts。SQL / 查询注入SQL / query injection用户输入被插值进查询字符串。任何 DB 节点在parameters.query内出现{{ ... }}——n8n 会在驱动绑定参数之前把它替换进 SQL 文本因此这是注入向量。正确做法Postgres/MySQL 用$1, $2占位符 parameters.options.queryReplacementMongo 用对象过滤器。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase 段。底层原理详见该文档queryReplacement接受逗号分隔列表每段成为一个绑定参数{{ $json.email }},{{ $json.id }}→$1, $2值只经驱动绑定、永不接触 SQL 文本MySQL 节点同样用$1,$2queryReplacement非原生?节点会归一化到驱动。连接 bug合法但断路Connection bugs: valid but brokenMerge 接了 3 个来源但numberOfInputs仍是 2。第三个来源被静默丢弃。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdMerge 段。numberOfInputs默认 2画布上 3 条线中的第 3 条连到了不存在的输入槽修复为与线数一致后务必用n8n_get_workflow核对parameters.numberOfInputs与connections中源条目数一致。Merge 索引差一off-by-one。parameters.useDataOfInput是1 索引的对应 UI 的 Input 1/2/3而connections.source.main[idx]与其他数组一样是0 索引。翻译规则useDataOfInput: N由main[N-1]处的连接供数。错位时下游拿到的数据形状对、内容错看起来完全正常。唯一可靠的核验方式是用n8n_get_workflow读connections对象确认。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdMerge错误输出已启用但未接线或已接线但未启用。若parameters.onError是continueErrorOutput而节点的错误输出为空失败项被静默丢弃若节点接了错误分支但onError未设置分支不可达失败会中止整个工作流。validate_workflow自 n8n-mcp ≥ 2.63.0 起会把两者都标为警告但都不会翻转valid:false所以仍是审查项。按节点类型定位错误输出它是节点自然输出之后的最后一个main[]槽——单输出节点如 HTTP Request是main[1]但 IF 上是main[2]其main[1]是正常 false 分支Switch / Split In Batches 同理。不要把多输出节点上已接线的第二分支误认为未接线的错误输出。→ n8n-validation-expertSwitch没有兜底输出fallback。缺少parameters.options.fallbackOutput: extra时未匹配任何规则的条目被静默丢弃。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSwitch 段。修复示例设置options.fallbackOutput: extra并用options.renameFallbackOutput命名同时给每个规则输出命名接线后确认兜底分支通向真实去处日志、告警或 NoOp——启用了兜底却连到空处丢数据效果一样。Webhook API 工作流执行敏感操作的 webhook 使用parameters.authentication: none。敏感 变更状态、发送外部消息、触碰生产数据、触发付费动作。任何拿到 URL 的人都能触发。将authentication设为basicAuth/headerAuth并匹配对应凭据。→ n8n-workflow-patternswebhook、n8n-mcp-tools-expert凭据错误分支返回 HTTP 200。每个 Respond 节点的responseCode默认都是 200包括错误路径。调用方看到的成功与 body 中的失败自相矛盾——最坏的情况是调用方的错误处理永远不会触发。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhook。每个 Respond 分支都应显式设置responseCode4xx 表示调用方错误400 校验、401/403 鉴权、409 冲突、429 限流5xx 表示服务端错误。SHOULD FIX应在下次变更时修复Set 节点反模式Set 节点只喂 0 或 1 个下游消费者——最常见的反模式。删除它把表达式内联到消费者处。例外2 消费者共用一个非平凡派生值或子工作流的最终 Return 节点。→ n8n-expression-syntaxThe Set-node antipattern and branch convergenceSet 节点拼装邮件 / Slack 正文。在通信节点的 body 字段内联构建。→ n8n-expression-syntaxSet 节点在写节点前映射字段。直接在写节点的逐字段表达式槽内映射。→ n8n-node-configuration多个连续 Set 节点各定义一个字段。合并为一个或直接消除。→ n8n-expression-syntaxCode 节点反模式Code 节点做纯单条目整形.map/.filter/.find、字段改名、可选链。改用表达式或 Edit Fields 的 arrow-function IIFE——结果相同约快百倍更可读。→ n8n-code-javascripttransform gatekeeperCode 节点使用crypto.createHash/crypto.createHmac。改用原生 Crypto 节点nodes-base.crypto。反复出现的疏漏。→ n8n-code-javascriptCode 节点解析 XML / SOAP / RSS。用原生 XML 节点nodes-base.xml Edit Fields 做提取。→ n8n-code-javascriptCode Set 节点组合Set 建输入、Code 做变换。一个 Edit Fields arrow-function IIFE 两者兼做。→ n8n-code-javascript能用 JS 却用了 Python Code 节点。约 95% 的场景推荐 JSPython 留给其标准库强项regex、hashlib、statistics且仅当用户明确要求时。→ n8n-code-python表达式纪律Expression discipline分支繁多 / 多步工作流深处使用$json.x。改用$(Source Node).item.json.x以换取重构稳定性$json形式在插入中间节点或上下文被清空时会静默失效。→ n8n-expression-syntaxnon-negotiable分支汇合后下游仍用$json引用。最后触发的分支胜出结果不确定。在合并点插入 NoOpCombine Inputs并按名字引用它分支形状不一致时用 Set 归一化。→ n8n-expression-syntax用 DateTime 节点做日期运算 / 格式化。改用内联 Luxon 表达式DateTime.fromISO(...).toFormat(...)。→ n8n-expression-syntax任何表达式中使用$env.X。不工作运行时抛错。改用$vars.X付费套餐、Data Table 或凭据存密钥。→ n8n-expression-syntax.all().map()/filter()/reduce()聚合却未开executeOnce: true。每个输入条目都会重跑整次聚合——浪费算力且本应输出 1 条却输出 N 条相同结果。当.all()是以当前条目为键的逐条查找时不要开executeOnce。→ n8n-expression-syntaxSlack / 通信节点Block Kit 以裸数组传入。会静默以纯文本发出。包装为{{ { blocks: ... } }}。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSlack。注意按节点名引用来源$(Build Message).item.json.blocks而非$json且不要用 stringify-then-reparse 的杂交写法。线程回复发成了顶层消息——thread_ts未设置或位置错误。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSlack。字段位置在不同版本间有迁移旧文档放在otherOptions用get_node确认。operation 用了 UI 显示名send而非内部值post。用get_node确认。UI 标签与存储值经常分叉如 Gmail/Supabase 的 Get Many →getAll。→ n8n-node-configuration数据库select/ query 的无匹配路径接 IF但未设alwaysOutputData。无匹配 零条目 IF 永不触发。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase多步写入需要原子性却拆在多个节点。n8n 不存在跨节点事务合并进一个executeQuery并显式设置options.queryBatching: transaction不要依赖默认值它随节点版本漂移单查询与独立批处理是其他模式。Supabase 的 REST 层没有事务需要原子性时直连同一数据库的 Postgres 节点。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdDatabase写节点INSERT/UPDATE/DELETE后接期待其输出的节点却未设alwaysOutputData。写操作常返回 0 条而卡住整条链。→ n8n-node-configurationWebhook / Respond to Webhook请求/响应 API 却把responseMode留在onReceived。调用方永远看不到计算出的结果改用responseNode简单场景可用lastNode同步返回最后节点输出。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhook所有失败一律返回 500。映射状态码400 校验、401/403 鉴权、409 冲突、429 限流。→ n8n-node-configurationrespondWith: json的 body 用JSON.stringify(...)构建。会双重编码。在表达式模式直接传对象字面量{{ { status: ok, id: ... } }}让节点序列化一次。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdWebhookwebhook 路径上的易失败节点HTTP/DB/API没有错误分支。失败会中止工作流调用方只收到 n8n 的通用错误。接onError: continueErrorOutput 一个 5xx Respond并验证接线。→ n8n-error-handling、n8n-workflow-patternswebhookHTTP Request认证头直接写进headerParameters而非凭据。改用 Bearer Auth / Header Auth 凭据。→ n8n-node-configuration、n8n-mcp-tools-expert同时通过headerParameters和凭据的 header auth 设置头。二者冲突。→ n8n-node-configuration网络调用节点HTTP/通信/DB/AI未开retryOnFail。瞬态 429 和抖动会表现为硬失败。瞬态失败处理暂时归入节点配置。→ n8n-node-configuration调度触发器业务关键调度没有显式工作流时区。夏令时和实例迁移会改变触发时刻。时区是工作流级设置Workflow Settings → Timezone规则内部没有时区字段可设cron 同时支持 5 字段Minute Hour DoM Month DoW与 6 字段带秒两种格式简单周期用 interval 模式更不易错。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSchedule调度触发的工作流不幂等。实例在触发时刻宕机该次运行直接被跳过没有补跑队列重启又可能重复触发。设计成跑两次结果一致必要时在工作流开头比对上次成功运行与预期节奏并追赶补跑。→ n8n-node-configuration → NODE_FAMILY_GOTCHAS.mdSchedule结构与模式本可套用既有模式webhook、HTTP API、数据库、AI、调度、批处理的工作流没有可辨识结构。重塑为标准模式。→ n8n-workflow-patterns假设扇出分支并行执行。n8n 是顺序执行的真正的并发需要子工作流分发。子工作流专项技能尚待建立先记录该限制。→ n8n-workflow-patterns大条目量流程逐条干活而批处理/聚合能削减开销。→ n8n-workflow-patternsAI Agent / Code Tool若存在自定义 Code Tool 返回非字符串如[{json:{...}}]或使用$fromAI/$input/$helpers——这些在 Code Tool 沙箱中都不存在返回值必须是字符串。→ n8n-code-tool工具名称或描述过于泛化 / 为空。模型无法判断何时调用它描述本身就是 prompt 的一部分。用动词开头的具体名称。更深的 agent 指南尚待专项技能。→ n8n-code-toolNICE TO HAVE顺带打磨命名泛化节点名HTTP Request1、Set2、Postgres1。Fetch order details上的运行时失败能立刻定位断点HTTP Request3对运维人员毫无信息量。按节点在工作流中的职责重命名。→ n8n-workflow-patterns工作流名不是动词开头Send weekly customer report而非Customer report sender。句子大小写、无 emoji、无尾随版本号。→ n8n-workflow-patterns可读性工作流description为空或只有一行。写两句它做什么、为什么存在为什么是最容易丢失的部分。→ n8n-workflow-patternsCode 节点没有一行注释解释为何不用更简单的工具。→ n8n-code-javascript多行表达式未缩进 / 无注释。多数 n8n 用户不是程序员——像真实代码一样排版。→ n8n-expression-syntax汇报发现严重性优先、域分组、指向规范技能按严重性分组、域内再分组。每条发现给出受影响的节点、一句话描述、负责修复的规范技能。可复制的汇报模板原文摘录MUST FIX Security - Node Send webhook: bearer token typed into headerParameters value. - n8n-mcp-tools-expert (credentials) - Node Lookup user: {{ $json.email }} interpolated into parameters.query. - NODE_FAMILY_GOTCHAS.md (Database) Connections - Node Merge customer Stripe: 3 sources wired but parameters.numberOfInputs 2; third drops. - NODE_FAMILY_GOTCHAS.md (Merge) SHOULD FIX Set-node antipattern - Node Set customer_id: feeds one consumer; inline at Lookup customer. - n8n-expression-syntax ...与验证技能体系的协同这份清单不是孤立的。它与 n8n-validation-expert 中的验证回路互为补充回路负责建得对不对清单负责审得够不够。配套资源ERROR_CATALOG.md九类错误类型missing_required约占 45%、invalid_value约 28%、type_mismatch约 12% 等的完整示例与修复对照FALSE_POSITIVES.md哪些警告可接受n8n-mcp ≥ 2.63.0 后在源头修复了经典误报无需忽略的已知误报清单已不存在剩余警告要么是安全/弃用通知、要么是ai-friendly/strict下的最佳实践建议审查前可先用n8n_audit_instance做实例级扫描再用n8n_get_workflow逐工作流核对修复密钥类发现用n8n_manage_credentials结构类发现可考虑n8n_autofix_workflowapplyFixes: false先预览confidenceThreshold控制高/中/低置信度门槛fixTypes可限定 expression-format、typeversion-upgrade 等类型详见 n8n-autofix-workflow.ts。最后重申两条底线MUST FIX 项必须先经用户确认再动手安全与连接变更的爆炸半径大以及每个发现都要落在 JSON 术语上——让审查结果可复现、可定位、可修复。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考