n8n 节点属性依赖displayOptions完全指南从字段可见性到依赖排查【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp本文以 n8n-mcp 项目的data/skills/n8n-node-configuration/DEPENDENCIES.md为骨架系统讲解 n8n 节点配置中最容易被忽略却又决定成败的机制——属性依赖Property Dependencies。无论你是通过 Claude / Cursor 等 AI 助手借助 n8n-mcp 的get_node、validate_node工具构建工作流还是手工在 n8n 编辑器中配置节点理解displayOptions的 show/hide 规则、AND/OR 逻辑、依赖链与自动清理auto-sanitization行为都能让你从报错后瞎猜升级为按依赖链一次配置成功。什么是属性依赖Property Dependencies定义属性依赖是一组规则它根据其他字段的取值控制当前字段在 n8n 界面中是否可见以及是否必填。底层机制字段定义中的displayOptions声明即节点 schema 的一部分。设计目的只展示与当前操作相关的字段减少界面噪音隐藏与当前模式无关的字段避免误填简化配置体验简单模式 vs 高级模式的渐进式披露在配置源头就阻止无效组合的产生降低校验失败率。举个最直观的例子HTTP Request 节点在methodGET时根本不会出现body字段——因为 GET 请求不需要请求体。这不是界面 bug而是displayOptions把body的可见性绑定到了sendBodytrue与method ∈ (POST, PUT, PATCH, DELETE)这两个条件上。在 n8n-mcp 项目中这套机制被正式建模为独立服务属性依赖服务 会从节点 schema 中提取出每个字段的dependsOn依赖条件、构建依赖图dependency graph并给出哪些字段是控制开关controller的配置建议。也就是说AI 助手在生成节点配置时正是通过解析这类displayOptions规则来理解什么字段什么时候出现。displayOptions 结构详解基础格式一个带依赖规则的字段在节点 schema 中长这样{ name: fieldName, type: string, displayOptions: { show: { otherField: [value1, value2] } } }语义翻译当otherField的取值等于value1或value2时显示fieldName字段。show 与 hide 两个方向displayOptions下有两个互逆的块语义恰好相反show最常用——条件满足时显示字段{ name: body, displayOptions: { show: { sendBody: [true] } } }含义当sendBody true时显示body字段。hide较少用——条件满足时隐藏字段{ name: advanced, displayOptions: { hide: { simpleMode: [true] } } }含义当simpleMode true时隐藏advanced字段即只有高级模式才展示高级选项。在 属性依赖服务 的实现中show块内的每个条件会被提取为condition: equals的依赖项而hide块则被映射为condition: not_equals的依赖项——这与 UI 语义严格对应show 要求命中才可见hide 要求命中才隐藏。多个条件 AND 逻辑同一个show块里出现多个键时所有条件必须同时满足{ name: body, displayOptions: { show: { sendBody: [true], method: [POST, PUT, PATCH] } } }含义仅当sendBody true且method为POST、PUT或PATCH之一时body才显示。多个值 OR 逻辑同一个键对应多个候选值时命中任意一个即可{ name: someField, displayOptions: { show: { method: [POST, PUT, PATCH] } } }含义method POST或PUT或PATCH任意一个成立即显示。这条规则同样被源码精确复现在 checkVisibility 实现 中show条件使用配置值不在期望集合中即隐藏的判断hide条件使用配置值在期望集合中即隐藏的判断多个 show 键之间是逐个检查的 AND 关系。速记口诀键之间是 AND值之间是 OR。四大常见依赖模式模式 1布尔开关Boolean Toggle适用场景可选的特性开关开关决定一组字段是否出现。典型案例HTTP Request 的sendBody → body。// 字段: sendBody (boolean) { name: sendBody, type: boolean, default: false } // 字段: body (依赖 sendBody) { name: body, displayOptions: { show: { sendBody: [true] } } }交互流程用户先看到sendBody复选框勾选后body字段出现取消勾选body字段隐藏。模式 2资源/操作级联Resource/Operation Cascade适用场景resource operation 组合决定展示哪些字段是 Slack、Google Sheets、Airtable 等资源型节点的通用结构。典型案例Slack 的 message 资源下post 与 update 显示完全不同的字段。// 操作: post —— 需要 channel { name: channel, displayOptions: { show: { resource: [message], operation: [post] } } } // 操作: update —— 需要 messageId { name: messageId, displayOptions: { show: { resource: [message], operation: [update] } } }交互流程用户选择resourcemessage选择operationpost→ 看到channel切到operationupdate→channel隐藏、messageId出现。这正是 n8n 中不同操作 不同必填字段的根源。参见 n8n-node-configuration 技能主文档 中 operation-aware 配置理念的完整论述。模式 3类型专属配置Type-Specific Configuration适用场景条件节点的操作符类型不同所需字段不同。典型案例IF 节点的字符串条件——二元操作符需要value2一元操作符如isEmpty不需要。// 二元操作符: 需要 value2 { name: value2, displayOptions: { show: { conditions.string.0.operation: [equals, notEquals, contains] } } } // 一元操作符: 隐藏 value2 { displayOptions: { hide: { conditions.string.0.operation: [isEmpty, isNotEmpty] } } }注意这里依赖键是带路径的conditions.string.0.operation——说明 displayOptions 可以直接引用嵌套在集合内部的字段值这是嵌套依赖的一种形态。模式 4方法专属字段Method-Specific Fields适用场景HTTP 方法不同可用选项不同。典型案例HTTP Request 中query 参数所有方法都能带但 body 只有部分方法能带。// Query 参数: 所有方法都可以 { name: queryParameters, displayOptions: { show: { sendQuery: [true] } } } // Body: 仅特定方法 { name: body, displayOptions: { show: { sendBody: [true], method: [POST, PUT, PATCH, DELETE] } } }本节的 HTTP 与条件节点操作级配置示例可进一步参考 OPERATION_PATTERNS.md 中 HTTP API 节点章节 与 Conditional Nodes 章节。如何查找属性依赖get_node 的两种模式在 n8n-mcp 中AI 助手通过get_node工具探查字段可见性规则。相关完整参数说明见 get_node 工具文档。方式一search_properties 模式按名字搜当校验报缺字段而你压根没在 schema 里看到该字段时用关键词搜索它// 查找与 body 相关的所有属性及其依赖规则 get_node({ nodeType: nodes-base.httpRequest, mode: search_properties, propertyQuery: body });该模式底层由 PropertyFilter.searchProperties 实现它会递归遍历属性树包括 collection / fixedCollection 嵌套按精确匹配 前缀匹配 包含匹配 描述匹配打分排序最多返回 20 条maxPropertyResults可调并附带属性在树中的完整路径。这对定位body、auth、headers这类高频字段尤其有效。方式二detail: full 看完整 schema// 获取带 displayOptions 的完整节点 schema get_node({ nodeType: nodes-base.httpRequest, detail: full });完整模式会返回所有属性及其displayOptions规则约 3-8K token代价是响应较大仅当 standard 详情默认约 1-2K token覆盖 95% 的配置需求不够时再升级。决策路径可概括为新建配置先用 standard → 找不到特定字段用search_properties→ 还不够再用full。何时该用✅ 应该用校验报missing field但配置里根本没出现该字段某个字段莫名其妙出现/消失需要理解是什么在控制字段可见性正在构建动态配置工具或自动生成配置。❌ 不必用常规简单配置standard 详情足够刚开始配置、字段要求一目了然时。复杂依赖示例三层链式依赖示例 1HTTP Request 完整流程POST JSON body场景配置一个携带 JSON body 的 POST 请求。这是一个典型的父属性先行依赖链。Step 1先设 method{ method: POST // → sendBody 变为可见 }Step 2开启 sendBody{ method: POST, sendBody: true // → body 字段出现且必填 }Step 3配置 body 的 contentType{ method: POST, sendBody: true, body: { contentType: json // → content 字段出现且必填 } }Step 4填充 content{ method: POST, sendBody: true, body: { contentType: json, content: { name: John, email: johnexample.com } } } // ✅ 校验通过完整依赖链methodPOST → sendBody 可见 → sendBodytrue → body 可见 必填 → body.contentTypejson → body.content 可见 必填这条链与 OPERATION_PATTERNS.md 中的 POST with JSON 最小配置 完全一致method url authentication起步sendBody: true唤起bodycontentType: json决定content为对象结构。示例 2IF 节点操作符依赖场景字符串比较不同操作符需要不同字段。二元操作符equals{ conditions: { string: [ { operation: equals // → value1 必填 // → value2 必填 // → singleValue 不应设置 } ] } }一元操作符isEmpty{ conditions: { string: [ { operation: isEmpty // → value1 必填 // → value2 不应设置 // → singleValue 应为 true自动补全 } ] } }依赖对照表Operatorvalue1value2singleValueequalsRequiredRequiredfalsenotEqualsRequiredRequiredfalsecontainsRequiredRequiredfalseisEmptyRequiredHiddentrueisNotEmptyRequiredHiddentrue示例 3Slack 操作矩阵场景Slack message 资源下不同操作展示不同字段。以下是 n8n-mcp 通过get_node({nodeType: nodes-base.slack})即可确认的操作级字段要求SKILL.md 也给出了同样结论// post message { resource: message, operation: post // 显示: channel (必填), text (必填), attachments, blocks } // update message { resource: message, operation: update // 显示: messageId (必填), text (必填), channel (可选) } // delete message { resource: message, operation: delete // 显示: messageId (必填), channel (必填) // 隐藏: text, attachments, blocks } // get message { resource: message, operation: get // 显示: messageId (必填), channel (必填) // 隐藏: text, attachments, blocks }字段可见性矩阵FieldpostupdatedeletegetchannelRequiredOptionalRequiredRequiredtextRequiredRequiredHiddenHiddenmessageIdHiddenRequiredRequiredRequiredattachmentsOptionalOptionalHiddenHiddenblocksOptionalOptionalHiddenHidden嵌套依赖Nested Dependencies是什么定义依赖发生在对象属性内部——父对象的值决定子对象的结构。典型案例HTTP Request 的body.contentType决定body.content是 JSON 对象还是表单字段数组。// contentTypejson → content 是对象 { body: { contentType: json, content: { key: value } } } // contentTypeform-data → content 是字段数组 { body: { contentType: form-data, content: [ { name: field1, value: value1 } ] } }处理策略先父后子// 第 1 步: 先设父属性 { body: { contentType: json // 父属性先行 } } // 第 2 步: 再按父值决定的结构填子属性 { body: { contentType: json, content: { // JSON 对象格式 key: value } } }之所以必须先父后子是因为校验器需要先知道contentType才能判断content应该是什么结构。PropertyDependencies服务也会为 collection / fixedCollection 类型的属性自动附加提示该属性包含可能自带依赖的嵌套属性见 extractDependency 的 notes 生成逻辑提醒 AI 先解析父结构。自动清理Auto-Sanitization与依赖的关系自动清理能修复什么操作符结构问题IF / Switch 节点singleValue这类 UI 元数据会在保存时被自动补全。示例一元操作符缺singleValue时// 你配置的缺少 singleValue { type: boolean, operation: isEmpty // 缺 singleValue } // 自动清理后 { type: boolean, operation: isEmpty, singleValue: true // ✅ 自动补上 }这在源码中确有实现节点清理器 node-sanitizer.ts 定义了UNARY_OPERATORS集合true、false、isNumeric、empty、notEmpty、exists、notExists对 IF v2.2 与 Switch v3.2 这类 filter-based 节点执行结构规范化sanitizeFilterBasedNode相应地n8n-validation.ts 的 validateOperatorStructure 刻意不校验singleValue——因为 n8n 运行时根据操作符名称推导一元性该标志只是写入路径上的 UI 元数据。自动清理不修复什么缺失的必填业务字段自动清理不会替你补channel、messageId这类业务字段。// 你配置的缺 channel { resource: message, operation: post, text: Hello // 缺必填字段: channel } // 自动清理不会补——必须自己加 { resource: message, operation: post, channel: #general, // ← 必须手动添加 text: Hello }实践结论让自动清理去处理结构元数据singleValue、条件 id 等而业务必填字段必须依据依赖链亲手补齐。依赖问题排查指南问题 1字段 X 必填但根本看不见报错{ type: missing_required, property: body, message: body is required }但配置里看不到 body 字段解法用search_properties查清 body 的可见条件再补齐触发它的上游字段。// 检查 body 的依赖 get_node({ nodeType: nodes-base.httpRequest, mode: search_properties, propertyQuery: body }); // 发现 body 在 sendBodytrue 时显示 // 于是补上 sendBody { method: POST, sendBody: true, // ← 加上后 body 出现了 body: {...} }问题 2切换操作后字段消失场景post 配置切到 update 后channel还在、text还在但报 messageId is required。原因不同操作 不同必填字段。update 需要messageId而 post 才需要channel必填。解法// 先确认新操作的必填项 get_node({ nodeType: nodes-base.slack }); // 按 update 的要求重新配置 { resource: message, operation: update, messageId: 1234567890, // update 必填 text: Updated, channel: #general // update 可选 }问题 3校验通过了但字段没保存场景字段在保存时被依赖规则剥离。示例// 配置 { method: GET, sendBody: true, // ❌ GET 不支持 body body: {...} // 这个会被剥离 } // 保存后 { method: GET // body 因 methodGET 隐藏而被移除 }解法从一开始就遵守依赖。// 正确做法 —— 先查 body 的依赖条件 get_node({ nodeType: nodes-base.httpRequest, mode: search_properties, propertyQuery: body }); // 看到 body 仅对 POST/PUT/PATCH/DELETE 显示 // 改用正确的方法 { method: POST, sendBody: true, body: {...} }高级模式模式 1带回退的条件必填示例channel 字段既可以是字符串也可以是表达式两种都合法。// 选项 1: 字符串 { channel: #general } // 选项 2: 表达式 { channel: {{$json.channelName}} } // 校验两者都接受模式 2互斥字段二选一示例用 ID 或名字二选一不可同时。// 用 messageId { messageId: 1234567890 // name 不需要 } // 或用 messageName { messageName: thread-name // messageId 不需要 } // 依赖规则保证只有一个必填模式 3渐进式复杂度简单/高级模式示例简单模式只显示 text高级模式显示 attachments、blocks、metadata。// 简单模式 { mode: simple, text: {{$json.message}} // 高级字段全部隐藏 } // 高级模式 { mode: advanced, attachments: [...], blocks: [...], metadata: {...} // 简单字段隐藏高级字段显示 }最佳实践✅ 应该做卡住时先查依赖get_node({nodeType: ..., mode: search_properties, propertyQuery: ...});先配置父属性先定method、resource、operation再填依赖字段。切换操作后重新校验操作变了必填要求就变了。validate_node({nodeType: ..., config: {...}, profile: runtime});把校验报错当依赖提示读Error: body required when sendBodytrue → Hint: 设置 sendBodytrue 以启用 body❌ 不要做无视依赖报错——报body 不可见就去查 displayOptions而不是硬塞字段。一次性硬编码所有可能的字段——会被隐藏的字段会被剥离徒增噪音。假设不同操作的配置可以互相套用——每个操作有自己独立的必填要求。小结核心概念displayOptions控制字段可见性show 条件匹配时出现hide 条件匹配时消失多个条件 AND 逻辑多个值 OR 逻辑。常见模式布尔开关sendBody → body资源/操作级联不同操作 → 不同字段类型专属配置string vs boolean 条件方法专属字段GET vs POST。排查三板斧字段必填但不可见 → 查依赖字段切换后消失 → 操作改变了要求字段保存不了 → 被依赖规则隐藏。可用工具get_node({mode: search_properties})—— 查找属性依赖get_node({detail: full})—— 查看含 displayOptions 的完整 schemaget_nodestandard—— 查看操作级必填要求校验报错 —— 自带依赖提示。关联资料均位于 n8n-node-configuration 技能目录SKILL.md —— 节点配置主指南渐进式披露与操作感知配置OPERATION_PATTERNS.md —— 按节点类型组织的常见配置模式与最小配置示例NODE_FAMILY_GOTCHAS.md —— 各节点家族的静默失败陷阱。附displayOptions 快速参考一段浓缩版速查字段可见性规则 三大最常见依赖模式 查找方法。displayOptions 机制{ name: body, displayOptions: { show: { sendBody: [true], method: [POST, PUT, PATCH] } } }翻译body字段在sendBody true且method为 POST、PUT 或 PATCH 时显示。三大常见模式速览模式 1布尔开关HTTP Request sendBody{ sendBody: true // → body 字段出现 }模式 2操作切换Slack resource/operation{ resource: message, operation: post // → 显示: channel, text, attachments 等 } { resource: message, operation: update // → 显示: messageId, text字段不同 }模式 3类型选择IF 节点条件{ type: string, operation: contains // → 显示: value1, value2 } { type: boolean, operation: equals // → 显示: value1, value2 及不同的操作符 }查找依赖的两种调用// 方式一: search_properties 按名搜索 get_node({ nodeType: nodes-base.httpRequest, mode: search_properties, propertyQuery: body }); // 返回匹配 body 的属性路径及描述 // 方式二: full 详情看完整 schema get_node({ nodeType: nodes-base.httpRequest, detail: full }); // 返回含 displayOptions 规则的完整 schema何时使用校验失败且不理解为什么某个字段缺失/必填时。处理条件必填字段Conditional Requirements有些字段只在特定条件下必填。两种最常见的发现与满足路径如下。示例HTTP Request 的 body场景body字段必填但只在特定条件下。规则body 必填当且仅当: - sendBody true 且 - method ∈ (POST, PUT, PATCH, DELETE)三种发现方式// 方式 1: 读校验报错 validate_node({...}); // Error: body required when sendBodytrue // 方式 2: 搜索属性 get_node({ nodeType: nodes-base.httpRequest, mode: search_properties, propertyQuery: body }); // 显示: body 属性及其 displayOptions 规则 // 方式 3: 最小配置迭代 // 先不带 body校验会告诉你是否需要示例IF 节点的 singleValue场景singleValue只对一元操作符出现。规则singleValue 应为 true 当: - operation ∈ (isEmpty, isNotEmpty, true, false)好消息自动清理会自动补全无需手动处理。手动核验get_node({ nodeType: nodes-base.if, detail: full }); // 显示含操作符专属规则的完整 schema掌握属性依赖本质上就是掌握 n8n 节点 schema 的条件编译逻辑。下次再遇到字段明明必填却找不到切换操作后配置失效这类问题先get_node({mode: search_properties})问一句这个字段被谁控制再顺着依赖链从父到子逐层补齐——配置一次通过率会立竿见影地提升。【免费下载链接】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），仅供参考