---

name: n8n-expression-syntax description: 验证 n8n 表达式语法并修复常见错误。在编写 n8n 表达式、使用 {{}} 语法、访问 $json/$node 变量、排查表达式错误或在工作流中处理 webhook 数据时使用。 risk: unknown source: community

n8n 表达式语法

编写正确 n8n 工作流表达式的专家指南。

何时使用

• 你需要编写或调试使用 {{ ... }} 语法的 n8n 表达式。
• 任务涉及 $json、$node、webhook 负载或与表达式相关的工作流错误。
• 你需要在 n8n 节点和参数中使用语法正确的动态值。

---

表达式格式

n8n 中所有动态内容使用双花括号：

{{expression}}

示例：

✅ {{$json.email}}
✅ {{$json.body.name}}
✅ {{$node["HTTP Request"].json.data}}
❌ $json.email  (无花括号 - 被视为纯文本)
❌ {$json.email}  (单花括号 - 无效)

---

核心变量

$json - 当前节点输出

访问当前节点的数据：

{{$json.fieldName}}
{{$json['field with spaces']}}
{{$json.nested.property}}
{{$json.items[0].name}}

$node - 引用其他节点

访问任何前置节点的数据：

{{$node["Node Name"].json.fieldName}}
{{$node["HTTP Request"].json.data}}
{{$node["Webhook"].json.body.email}}

重要：

• 节点名称必须用引号包裹
• 节点名称区分大小写
• 必须与工作流中的确切节点名称匹配

$now - 当前时间戳

访问当前日期/时间：

{{$now}}
{{$now.toFormat('yyyy-MM-dd')}}
{{$now.toFormat('HH:mm:ss')}}
{{$now.plus({days: 7})}}

$env - 环境变量

访问环境变量：

{{$env.API_KEY}}
{{$env.DATABASE_URL}}

---

关键：Webhook 数据结构

最常见错误：Webhook 数据不在根级别！

Webhook 节点输出结构

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // ⚠️ 用户数据在这里！
    "name": "John",
    "email": "john@example.com",
    "message": "Hello"
  }
}

正确的 Webhook 数据访问

❌ 错误: {{$json.name}}
❌ 错误: {{$json.email}}

✅ 正确: {{$json.body.name}}
✅ 正确: {{$json.body.email}}
✅ 正确: {{$json.body.message}}

原因：Webhook 节点将传入数据包装在 .body 属性下，以保留 headers、params 和 query 参数。

---

常见模式

访问嵌套字段

// 简单嵌套
{{$json.user.email}}

// 数组访问
{{$json.data[0].name}}
{{$json.items[0].id}}

// 带空格的方括号表示法
{{$json['field name']}}
{{$json['user data']['first name']}}

引用其他节点

// 无空格的节点
{{$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}}

// 在对象属性中
{
  "name": "={{$json.body.name}}",
  "email": "={{$json.body.email}}"
}

---

何时不使用表达式

代码节点中不使用

代码节点使用直接 JavaScript 访问，不是表达式！

// ❌ 在代码节点中错误
const email = '={{$json.email}}';
const name = '{{$json.body.name}}';

// ✅ 在代码节点中正确
const email = $json.email;
const name = $json.body.name;

// 或使用代码节点 API
const email = $input.item.json.email;
const allItems = $input.all();

Webhook 路径中不使用

// ❌ 错误
path: "{{$json.user_id}}/webhook"

// ✅ 正确
path: "user-webhook"  // 仅静态路径

凭证字段中不使用

// ❌ 错误
apiKey: "={{$env.API_KEY}}"

// ✅ 正确
使用 n8n 凭证系统，而非表达式

---

验证规则

1. 始终使用 {{}}

表达式必须用双花括号包裹。

❌ $json.field
✅ {{$json.field}}

2. 有空格时使用引号

带空格的字段或节点名称需要方括号表示法：

❌ {{$json.field name}}
✅ {{$json['field name']}}

❌ {{$node.HTTP Request.json}}
✅ {{$node["HTTP Request"].json}}

3. 匹配确切节点名称

节点引用区分大小写：

❌ {{$node["http request"].json}}  // 小写
❌ {{$node["Http Request"].json}}  // 大小写错误
✅ {{$node["HTTP Request"].json}}  // 精确匹配

4. 不要嵌套 {{}}

不要双重包裹表达式：

❌ {{{$json.field}}}
✅ {{$json.field}}

---

常见错误

完整错误目录及修复方法，参见 COMMON_MISTAKES.md

快速修复

| 错误 | 修复 | |---------|------| | $json.field | {{$json.field}} | | {{$json.field name}} | {{$json['field name']}} | | {{$node.HTTP Request}} | {{$node["HTTP Request"]}} | | {{{$json.field}}} | {{$json.field}} |