n8n 表达式语法完全指南掌握 {{ }} 变量引用、Webhook 数据结构与常见错误排查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本篇技术指南以 n8n-mcp 仓库内置的 n8n Expression Syntax 技能包README.md 及同目录 SKILL.md、COMMON_MISTAKES.md、EXAMPLES.md为骨架系统讲解 n8n 工作流中表达式{{ }}的正确写法、核心变量$json、$node、$now、$env、最容易踩坑的 Webhook 数据结构、15 类常见错误的修复方法以及表达式与 Code 节点的选型与性能权衡。读完本文你将能写出可正确求值、可维护、无undefined报错的 n8n 表达式并借助 n8n-mcp 的校验工具在工作流部署前自动拦截表达式错误。一、表达式格式一切动态内容都必须使用双花括号n8n 中的所有动态内容都必须用双花括号包裹{{expression}}✅{{$json.email}}✅{{$json.body.name}}✅{{$node[HTTP Request].json.data}}❌$json.email缺少花括号会被当作字面文本原样输出❌{$json.email}单花括号语法非法n8n 只对{{ }}内部的内容求值其余一切字符都按字面文本处理。这正是大多数“表达式没生效”类问题的根源——不是表达式写错了而是根本没被包裹进花括号。裸表达式自动检测源码级防线n8n-mcp 的表达式校验器在部署前就能发现这类问题。expression-validator.ts 中维护了一份BARE_EXPRESSION_PATTERNS清单专门匹配缺少{{ }}包裹的裸变量引用{ pattern: /^\$json[.\[]/, name: $json }, { pattern: /^\$node\[/, name: $node }, { pattern: /^\$input\./, name: $input }, { pattern: /^\$execution\./, name: $execution }, { pattern: /^\$workflow\./, name: $workflow }, { pattern: /^\$prevNode\./, name: $prevNode }, { pattern: /^\$env\./, name: $env }, { pattern: /^\$(now|today|itemIndex|runIndex)$/, name: built-in variable },当字段值以$json.、$node[、$env.等开头却既不含{{也不以开头时校验器会给出警告提示用{{ ... }}包裹以真正求值见 expression-validator.ts。二、四大核心变量1.$json当前节点的输出数据{{$json.fieldName}} {{$json[field with spaces]}} {{$json.nested.property}} {{$json.items[0].name}}$json在表达式校验器中被识别为$json(\.[a-zA-Z_][\w]*|\[[^]\]|\[[^]\]|\[\d\])*模式expression-validator.ts支持点号访问、带引号的括号访问和数字索引。如果当前节点没有输入数据校验器还会额外产生一条Using $json but node might not have input data警告。2.$node引用任意前序节点的数据{{$node[Node Name].json.fieldName}} {{$node[HTTP Request].json.data}} {{$node[Webhook].json.body.email}}关键约束节点名必须放在引号内$node[HTTP Request]不能写$node.HTTP Request节点名区分大小写必须与工作流画布上的名称完全一致引用路径固定为.json前缀二进制数据则为.binary不能省略。校验器会提取$node[...]中的节点名与工作流实际存在的节点逐一比对未找到时直接报错Referenced node xxx not found in workflowexpression-validator.ts。3.$now当前时间戳Luxon DateTime{{$now}} {{$now.toFormat(yyyy-MM-dd)}} {{$now.toFormat(HH:mm:ss)}} {{$now.plus({days: 7})}}$now基于 Luxon 库支持toFormat、plus、minus、set、toISO等完整时间运算能力。4.$env环境变量{{$env.API_KEY}} {{$env.DATABASE_URL}}警告部分 n8n 实例启用了N8N_BLOCK_ENV_ACCESS_IN_NODE会完全封锁$env访问。如果$env报错改用以下替代方案将敏感值存入 n8n 凭据Credentials使用 SetEdit Fields节点手动录入值通过 Webhook 查询参数传入。三、 最关键陷阱Webhook 数据不在根节点而在.body下这是 n8n 表达式错误中最常见、最致命的一类Webhook 节点为了保留请求头、路径参数和查询参数会把用户提交的数据包裹在.body属性下。Webhook 节点输出结构{ headers: {...}, params: {...}, query: {...}, body: { // ⚠️ 用户数据在这里 name: John, email: johnexample.com, message: Hello } }正确与错误的访问方式❌ 错误: {{$json.name}} ❌ 错误: {{$json.email}} ✅ 正确: {{$json.body.name}} ✅ 正确: {{$json.body.email}} ✅ 正确: {{$json.body.message}}为什么Webhook 节点把收到的数据包在.body属性下是为了保留headers、params、query等元信息。判定方法很简单如果 Webhook 工作流里明明收到了字段却输出undefined十有八九是漏写了.body。四、常用表达式模式嵌套字段访问// 简单嵌套 {{$json.user.email}} // 数组访问 {{$json.data[0].name}} {{$json.items[0].id}} // 含空格字段用括号记法 {{$json[field name]}} {{$json[user data][first name]}}注意数组索引必须用方括号[0]写成{{$json.items.0.name}}是非法 JavaScript。引用其他节点// 无空格节点名 {{$node[Set].json.value}} // 带空格节点名常见 {{$node[HTTP Request].json.data}} {{$node[Respond to Webhook].json.message}} // Webhook 节点 {{$node[Webhook].json.body.email}}组合变量// 自动字符串拼接 Hello {{$json.body.name}}! // 拼进 URL https://api.example.com/users/{{$json.body.user_id}} // 拼进对象属性JSON 模式需要 前缀 { name: {{$json.body.name}}, email: {{$json.body.email}} }五、什么时候不要用表达式1. Code 节点直接用 JavaScript禁止{{ }}Code 节点内是直接的数据访问不是表达式字段// ❌ Code 节点内错误写法 const email {{$json.email}}; const name {{$json.body.name}}; // ✅ Code 节点内正确写法 const email $json.email; const name $json.body.name; // 或使用 Code 节点 API const email $input.item.json.email; const allItems $input.all();n8n-mcp 校验器对 Code 节点做了专门豁免在 validateParametersRecursive 中jsCode、pythonCode、functionCode等代码字段会被直接跳过——因为里面是 JavaScript/Python 源码而非 n8n 表达式做括号匹配会产生大量误报。2. Webhook 路径只支持静态路径// ❌ 错误 path: {{$json.user_id}}/webhook // ✅ 正确 path: user-webhook // 静态路径 path: user-webhook/:userId // 改用动态 URL 参数3. 凭据字段使用 n8n 凭据系统// ❌ 错误 apiKey: {{$env.API_KEY}} // ✅ 正确 // 使用 n8n 凭据系统而非表达式六、转换逻辑的优先级先表达式再 IIFE最后才 Code 节点在添加任何转换节点或编写任何转换代码之前按以下顺序决策命中即止第 1 步表达式{{ ... }}。放进消费字段即可。属性访问、方法链.map().filter().join()、三元表达式、字符串拼接、Luxon 日期运算——只要是无中间变量的“取 A 产 B”就该用表达式。这覆盖了绝大多数“帮我转换一下”的场景。第 2 步Edit Fields 字段内的箭头函数 IIFE。当逻辑需要中间变量、分支或注释但仍只作用于单条数据时直接在字段值里用立即执行的箭头函数包裹{{( () { const items $json.line_items; const subtotal items.reduce((sum, it) sum it.price * it.qty, 0); const tax subtotal * 0.08; return (subtotal tax).toFixed(2); })() }}外层(...)包裹函数、尾部()立即执行去掉任何一个 n8n 都会拒绝运行。函数内部拥有完整表达式作用域$json、$(Node)、$now、Luxon外加const/let、if/switch、try/catch和正则。不支持require和await。第 3 步Code 节点——最后手段。仅当需要跨整个数据集的多条目聚合$input.all()、白名单库或异步操作时使用。为什么顺序如此重要这不是风格问题而是可读性与性能问题。Code 节点运行在沙箱 VM 中每次调用都有启动和数据序列化开销——冷启动成本可能达到 500–1000ms 才会执行你的逻辑热态、大批量时摊销可将其视为常规场景成本而非普适常数。同样的逻辑用表达式或 Edit Fields IIFE 处理是进程内执行耗时仅为个位数毫秒完全跳过沙箱。对纯单条数据整形而言这是一个巨大且无功能差异的差距在每请求一次 Webhook 这类热路径上会被放大。此外表达式直接显示在使用它的字段里而不是藏在某个上游节点中需要别人点开才能理解。七、Set 节点反模式与分支汇聚删除只服务一个消费者的 Set 节点一个 SetEdit Fields节点如果唯一职责是从数据中提取某个值、再交给一个下游节点那它就是死重。直接在消费方内联表达式即可❌ Webhook → Set { customer_id: {{ $json.body.customer_id }} } → Postgres: WHERE id {{ $json.customer_id }} ✅ Webhook → Postgres: WHERE id {{ $(Webhook).item.json.body.customer_id }}Set 节点多了一次跳转、更多画布杂乱和一个重构隐患而它做的事消费方自己就能完成。若要干净地移除可使用n8n_update_partial_workflow用removeConnection拆掉 Set 的入出连接、addConnection直接从源节点直连消费方、patchNodeField把消费方表达式改为按节点名引用原始源最后removeNode删除 Set。快速自测数一下有几个下游节点引用了 Set 产出的字段。0 或 1 个→ 删除在消费方内联2 个以上→ 它可能值得保留。合法的保留例外2 个以上消费者读取同一派生值且派生逻辑非平凡命名有助于可读性且只需计算一次子工作流最终的 Return 节点用于塑形输出契约。此时“唯一消费者”是每个调用方Set 本身就是 API 边界——配合Include Other Fields: false可白名单化输出形状防止内部临时字段泄漏需要重命名或白名单字段并希望在一处集中体现而不是分散在多个消费者表达式里。分支汇聚用 NoOp 锚定当分支汇聚时IF/Switch/Merge 之后$json变成“最后触发的那个分支”——不确定且是错误数据的静默来源。应在汇聚点插入NoOp节点起个描述性名称如Combine Inputs让下游节点按名引用Branch A ──┐ ├─→ [NoOp: Combine Inputs] ──→ 下游使用 $(Combine Inputs).item.json.x Branch B ──┘NoOp 能扛住重构之后在它和消费者之间插入转换节点不会破坏$(Combine Inputs)引用。如果各分支产出不同形状的数据则改用 Set 节点归一化为同一形状——见上面的例外。更广泛地说在分支较多的流程中优先用$(Node).item.json.x而非深层$json.x。$json会在中间插入节点、或节点清空条目上下文Aggregate、Run for All 的 Code 节点、分支合并时失效这种失效是静默的——下游拿到错误数据却不报错。而按节点名引用无论源与消费者之间隔着什么都是无歧义的。八、四大验证规则速记#规则错误示例正确示例1始终使用{{ }}$json.field{{$json.field}}2空格/特殊字符用括号记法{{$json.field name}}{{$json[field name]}}3节点名精确匹配区分大小写{{$node[http request].json}}{{$node[HTTP Request].json}}4禁止嵌套{{ }}{{{$json.field}}}{{$json.field}}括号记法对有变音符号或特殊字符的键是强制要求{{$json[Gross Price w/o shipment]}}、{{$json[Cena brutto zł]}}均可正常求值。在源码层面n8n-mcp 的校验器对语法错误有严格检查expression-validator.ts以开头的表达式若存在未配对的{{报Unmatched expression brackets {{ }}检测到真正嵌套的表达式{{内再套{{报Nested expressions are not supported空表达式{{}}报Empty expression found。注意一个字段中多个独立表达式如{{ $json.a }} text {{ $json.b }}是合法的与嵌套表达式是两回事。九、15 类常见错误完整目录与修复完整的错误目录见 COMMON_MISTAKES.md以下按“错误—现象—修复”逐一列出#错误现象修复1缺少花括号$json.email字段显示字面文本加{{ }}2Webhook 数据访问{{$json.name}}输出undefined改用{{$json.body.name}}3字段名带空格{{$json.first name}}语法错误/undefined用{{$json[first name]}}4节点名带空格{{$node.HTTP Request.json}}无法访问其他节点数据用{{$node[HTTP Request].json}}5节点名大小写错误undefined与画布节点名完全一致6双重包裹{{{$json.field}}}输出中出现字面{{ }}只保留一层{{ }}7数组用点号{{$json.items.0.name}}语法错误用{{$json.items[0].name}}8Code 节点里写表达式输出字面{{$json.email}}直接用$json.email9$node引用缺引号{{$node[HTTP Request].json}}语法错误Unexpected identifier节点名加引号[HTTP Request]10属性路径错误undefined用表达式编辑器预览核对真实结构11非 JSON 上下文误用前缀输出带字面文本模式去掉仅 JSON 模式/整字段赋值时用12Webhook 路径用表达式路径不更新/校验报错改静态路径或动态参数:paramName13漏写.json如$node[Webhook].body.emailundefined补.json$node[Webhook].json.body.email14反引号模板串/拼接写在{{ }}外原样输出把模板串或拼接放进{{ }}内15空表达式{{}}输出字面{{ }}填入表达式内容关于第 11 条的补充前缀的正确用法前缀只在 JSON 模式或需要把整个字段值设为表达式结果时才需要// JSON 模式把属性设为表达式结果 { email: {{$json.body.email}} } // 文本模式不需要 Hello {{$json.body.name}}!非 JSON 上下文里会被当成字面文本解析输出形如johnexample.com。关于第 14 条的补充模板字符串其实完全支持反引号和本身不是问题——问题是缺少{{ }}。在表达式内部反引号模板串、可选链、括号访问都是 n8n 2.x Tournament 引擎完整支持的现代 JavaScript{{ $json.items.map(i ${i.name} — ${i.qty}).join(, ) }} {{ $json.user?.email }} {{ $json[some-prop] }}这也与源码中的注释相互印证n8n-mcp 校验器明确不再对模板字符串、可选链、任意键的括号访问做误报expression-validator.ts 注释记录为 live-verified, issue #338。自 n8n-mcp ≥ 2.63.0 起校验器对这些写法不再报错早期版本曾产生误报。十、真实工作示例完整可运行的示例集见 EXAMPLES.md以下精选三例示例 1Webhook 表单提交 → SlackWebhook 收到{ body: { name: John Doe, email: johnexample.com, message: Hello! } }Slack 节点文本字段New form submission! Name: {{$json.body.name}} Email: {{$json.body.email}} Message: {{$json.body.message}}示例 2HTTP 请求 → 数据库跨节点引用 时间戳HTTP Request 返回{data: {users: [{id: 123, name: Alice Smith, email: aliceexample.com, role: admin}]}}Postgres 节点 INSERT 语句INSERT INTO users (user_id, name, email, role, synced_at) VALUES ( {{$json.data.users[0].id}}, {{$json.data.users[0].name}}, {{$json.data.users[0].email}}, {{$json.data.users[0].role}}, {{$now.toFormat(yyyy-MM-dd HH:mm:ss)}} )示例 3多节点数据流Webhook → HTTP Request → EmailHTTP Request 的 URL 字段https://api.example.com/orders/{{$json.body.order_id}}Email 主题Order {{$node[Webhook].json.body.order_id}} ConfirmedEmail 正文Dear {{$node[HTTP Request].json.order.customer}}, Your order {{$node[Webhook].json.body.order_id}} has been confirmed! Total: ${{$node[HTTP Request].json.order.total}} Items: {{$node[HTTP Request].json.order.items.join(, )}}真实模板示例n8n template #2947 Weather to Slack工作流结构Webhook → OpenStreetMap API → Weather API → SlackSlack 斜杠命令输入/weather London{ body: { text: London } }OpenStreetMaphttps://nominatim.openstreetmap.org/search?q{{$json.body.text}}formatjsonNWS 天气 APIhttps://api.weather.gov/points/{{$node[OpenStreetMap].json[0].lat}},{{$node[OpenStreetMap].json[0].lon}}Slack 消息Weather for {{$json.body.text}}: Temperature: {{$node[Weather API].json.properties.temperature.value}}°C Conditions: {{$node[Weather API].json.properties.shortForecast}}十一、数据类型处理与高级模式数组{{$json.users[0].email}} // 首项 {{$json.users.length}} // 长度 {{$json.users[$json.users.length - 1].name}} // 末项 {{$json.users.map(u u.email).join(, )}} // 全部邮箱拼接对象与字符串{{$json.user.email}} // 点号无空格 {{$json[user data].email}} // 括号有空格/动态键 {{$json.email.toLowerCase()}} // 字符串方法 {{$json.message.replace(World, n8n)}} // 替换 {{$json.email.substring(0, 5)}} // 截取 {{$json.tags.split(,).join(, )}} // 拆分再拼接数字与条件{{$json.price * 1.1}} // 加 10% {{$json.quantity 5}} // 算术 {{$json.status active ? Active User : Inactive User}} // 三元 {{$json.email || no-emailexample.com}} // 默认值 {{$json.order.total 100 ? Premium Customer : Standard Customer}} // 多条件日期运算Luxon{{$now.plus({days: 7}).toFormat(yyyy-MM-dd)}} // 加 7 天 → 2025-10-27 {{$now.minus({hours: 24}).toISO()}} // 减 24 小时 → ISO {{DateTime.fromISO(2025-12-25).toFormat(MMMM dd, yyyy)}} // 指定日期格式化十二、性能表达式复杂度几乎免费一个常见顾虑是“复杂的{{ }}很慢”。事实恰恰相反——开销取决于 n8n求值表达式的次数而非每个表达式有多复杂。在 n8n 2.x 实例上的实测一个复杂表达式sqrt、split、reduce、算术混合与一个平凡表达式{{ $json.x 50 }}的每条开销几乎相同——约 0.2 ms/条因为其中约 90% 是 n8n 构建每条求值上下文的开销而非运行你的表达式。实践含义不要为了“提速”把一个能跑的表达式拆成节点链。每多一个节点都会按条重新求值并重新拷贝所有数据一个带更丰富表达式的节点优于三个带简单表达式的节点表达式约 0.2 ms/条比“逐条运行”模式的 Code 节点约 0.6 ms/条便宜约 3 倍但“一次处理全部”模式的 Code 节点更便宜约 0.02 ms/条因为它只跨越一次条目边界而非 N 次该差异只在数千条数据级别才明显以下都是亚 100ms 级别。十三、调试流程当表达式不工作时按顺序检查检查花括号是否被{{ }}包裹检查数据源是 Webhook 数据吗需要加.body检查空格字段名或节点名有空格用括号记法检查大小写节点名是否精确匹配检查路径属性路径是否正确数组要不要下标使用表达式编辑器点字段的 fx 图标打开编辑器实时预览实际结果检查上下文是 Code 节点吗去掉{{ }}。常见错误信息解读报错含义排查方向Cannot read property X of undefined父对象不存在检查数据路径是否漏了.body或数组下标X is not a function对非函数调用了方法检查变量类型表达式显示为字面文本缺少{{ }}补上花括号十四、表达式可用方法速查字符串.toLowerCase()、.toUpperCase()、.trim()、.replace()、.substring()、.split()、.includes()数组.length、.map()、.filter()、.find()、.join()、.slice()日期时间Luxon.toFormat()、.toISO()、.toLocal()、.plus()、.minus()、.set()数字.toFixed()、.toString()算术 - * / %十五、最佳实践清单✅ 应该做动态内容始终使用{{ }}含空格的字段名用括号记法Webhook 数据从.body引用其他节点的数据用$node按名引用在表达式编辑器里测试预览。❌ 不要做在 Code 节点里写表达式忘记给带空格的节点名加引号用多余{{ }}双重包裹假设 Webhook 数据在根层级它在.body下在 Webhook 路径或凭据字段里用表达式。五条核心规则来自技能文档的 Summary用{{ }}包裹表达式Webhook 数据在.body下Code 节点里没有{{ }}带空格的节点名加引号节点名区分大小写。十六、用 n8n-mcp 校验工具自动检查表达式除了人工对照规则n8n-mcp 提供了validate_workflow工具做部署前的三层校验结构、连接、表达式。其options.validateExpressions参数默认为true专门检查所有 n8n 表达式的语法与引用工具文档validate_workflow({workflow: myWorkflow}) // 全量校验含表达式 validate_workflow({workflow: myWorkflow, options: {profile: minimal}}) // 开发期快速检查 validate_workflow({workflow: myWorkflow, options: {validateExpressions: false}}) // 跳过表达式校验校验器能发现未配对的{{ }}、嵌套表达式、空表达式、裸变量引用、引用不存在的节点、缺失$前缀、$json用在无输入数据的节点上等。表达式校验通常只增加约 50–100ms 耗时远小于部署后发现错误再返工的成本。建议在n8n_create_workflow或n8n_update_partial_workflow之前始终先跑一次校验见 n8n-validate-workflow.ts。相关技能与延伸阅读n8n MCP Tools Expert学习如何用 MCP 工具验证表达式data/skills/n8n-mcp-tools-expert/n8n Workflow Patterns在真实工作流示例中看表达式的运用data/skills/n8n-workflow-patterns/n8n Node Configuration理解何时需要表达式data/skills/n8n-node-configuration/n8n Code JavaScript完整条目边界性能模型的深入讲解data/skills/n8n-code-javascript/n8n-mcp 技能总览data/skills/n8n-agents/README.md。【免费下载链接】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），仅供参考