n8n-expression-syntax

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Expression Syntax

n8n 表达式语法

Expert guide for writing correct n8n expressions in workflows.

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

Expression Format

表达式格式

All dynamic content in n8n uses double curly braces:

{{expression}}

Examples:

✅ {{$json.email}}
✅ {{$json.body.name}}
✅ {{$node["HTTP Request"].json.data}}
❌ $json.email  (no braces - treated as literal text)
❌ {$json.email}  (single braces - invalid)

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

{{expression}}

示例:

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

Core Variables

核心变量

$json - Current Node Output

$json - 当前节点输出

Access data from the current node:

javascript

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

访问当前节点的数据：

javascript

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

$node - Reference Other Nodes

$node - 引用其他节点

Access data from any previous node:

javascript

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

Important:

Node names must be in quotes
Node names are case-sensitive
Must match exact node name from workflow

访问任意前序节点的数据：

javascript

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

重要说明:

节点名称必须加引号
节点名称区分大小写
必须与工作流中的节点名称完全匹配

$now - Current Timestamp

$now - 当前时间戳

Access current date/time:

javascript

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

访问当前日期/时间：

javascript

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

$env - Environment Variables

$env - 环境变量

Access environment variables:

javascript

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

Warning: Some n8n instances have

N8N_BLOCK_ENV_ACCESS_IN_NODE

enabled, which blocks

$env

access entirely. If

$env

returns errors, use alternative approaches:

Store values in credentials instead
Use a Set node with manually entered values
Pass values through webhook query parameters

访问环境变量：

javascript

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

警告：部分n8n实例启用了

N8N_BLOCK_ENV_ACCESS_IN_NODE

，会完全阻止

$env

访问。如果

$env

返回错误，请使用替代方案：

将值存储在凭证中
使用Set节点手动输入值
通过webhook查询参数传递值

🚨 CRITICAL: Webhook Data Structure

🚨 重要提示：Webhook数据结构

Most Common Mistake: Webhook data is NOT at the root!

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

Webhook Node Output Structure

Webhook节点输出结构

javascript

{
  "headers": {...},
  "params": {...},
  "query": {...},
  "body": {           // ⚠️ USER DATA IS HERE!
    "name": "John",
    "email": "john@example.com",
    "message": "Hello"
  }
}

javascript

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

Correct Webhook Data Access

正确访问Webhook数据

javascript

❌ WRONG: {{$json.name}}
❌ WRONG: {{$json.email}}

✅ CORRECT: {{$json.body.name}}
✅ CORRECT: {{$json.body.email}}
✅ CORRECT: {{$json.body.message}}

Why: Webhook node wraps incoming data under

.body

property to preserve headers, params, and query parameters.

javascript

❌ 错误写法：{{$json.name}}
❌ 错误写法：{{$json.email}}

✅ 正确写法：{{$json.body.name}}
✅ 正确写法：{{$json.body.email}}
✅ 正确写法：{{$json.body.message}}

原因：Webhook节点会将传入数据包裹在

.body

属性下，以保留请求头、参数和查询参数。

Common Patterns

常见用法模式

Access Nested Fields

访问嵌套字段

javascript

// Simple nesting
{{$json.user.email}}

// Array access
{{$json.data[0].name}}
{{$json.items[0].id}}

// Bracket notation for spaces
{{$json['field name']}}
{{$json['user data']['first name']}}

javascript

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

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

// 空格字段使用括号语法
{{$json['field name']}}
{{$json['user data']['first name']}}

Reference Other Nodes

引用其他节点

javascript

// Node without spaces
{{$node["Set"].json.value}}

// Node with spaces (common!)
{{$node["HTTP Request"].json.data}}
{{$node["Respond to Webhook"].json.message}}

// Webhook node
{{$node["Webhook"].json.body.email}}

javascript

// 无空格的节点
{{$node["Set"].json.value}}

// 带空格的节点（很常见！）
{{$node["HTTP Request"].json.data}}
{{$node["Respond to Webhook"].json.message}}

// Webhook节点
{{$node["Webhook"].json.body.email}}

Combine Variables

变量组合

javascript

// Concatenation (automatic)
Hello {{$json.body.name}}!

// In URLs
https://api.example.com/users/{{$json.body.user_id}}

// In object properties
{
  "name": "={{$json.body.name}}",
  "email": "={{$json.body.email}}"
}

javascript

// 自动拼接
Hello {{$json.body.name}}!

// 在URL中使用
https://api.example.com/users/{{$json.body.user_id}}

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

When NOT to Use Expressions

不适用于表达式的场景

❌ Code Nodes

❌ Code节点

Code nodes use direct JavaScript access, NOT expressions!

javascript

// ❌ WRONG in Code node
const email = '={{$json.email}}';
const name = '{{$json.body.name}}';

// ✅ CORRECT in Code node
const email = $json.email;
const name = $json.body.name;

// Or using Code node API
const email = $input.item.json.email;
const allItems = $input.all();

Code节点使用直接JavaScript访问，而非表达式！

javascript

// ❌ 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();

❌ Webhook Paths

❌ Webhook路径

javascript

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

// ✅ CORRECT
path: "user-webhook"  // Static paths only

javascript

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

// ✅ 正确写法
path: "user-webhook"  // 仅支持静态路径

❌ Credential Fields

❌ 凭证字段

javascript

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

// ✅ CORRECT
Use n8n credential system, not expressions

javascript

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

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

Validation Rules

验证规则

1. Always Use {{}}

1. 始终使用{{}}

Expressions must be wrapped in double curly braces.

javascript

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

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

javascript

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

2. Use Quotes for Spaces and Special Characters

2. 空格和特殊字符需加引号

Field or node names with spaces, diacritics, or special characters require bracket notation:

javascript

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

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

// Bracket notation is mandatory for keys with special characters
✅ {{$json['Gross Price w/o shipment']}}
✅ {{$json['Cena brutto zł']}}

字段或节点名称包含空格、变音符号或特殊字符时，需使用括号语法：

javascript

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

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

// 含特殊字符的键必须使用括号语法
✅ {{$json['Gross Price w/o shipment']}}
✅ {{$json['Cena brutto zł']}}

3. Match Exact Node Names

3. 匹配节点全名

Node references are case-sensitive:

javascript

❌ {{$node["http request"].json}}  // lowercase
❌ {{$node["Http Request"].json}}  // wrong case
✅ {{$node["HTTP Request"].json}}  // exact match

节点引用区分大小写：

javascript

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

4. No Nested {{}}

4. 不要嵌套{{}}

Don't double-wrap expressions:

javascript

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

请勿重复包裹表达式：

javascript

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

Common Mistakes

常见错误

For complete error catalog with fixes, see COMMON_MISTAKES.md

完整错误目录及修复方案，请查看COMMON_MISTAKES.md

Quick Fixes

快速修复

Mistake	Fix
`$json.field`	`{{$json.field}}`
`{{$json.field name}}`	`{{$json['field name']}}`
`{{$node.HTTP Request}}`	`{{$node["HTTP Request"]}}`
`{{{$json.field}}}`	`{{$json.field}}`
`{{$json.name}}` (webhook)	`{{$json.body.name}}`
`'={{$json.email}}'` (Code node)	`$json.email`

错误写法	修复方案
`$json.field`	`{{$json.field}}`
`{{$json.field name}}`	`{{$json['field name']}}`
`{{$node.HTTP Request}}`	`{{$node["HTTP Request"]}}`
`{{{$json.field}}}`	`{{$json.field}}`
`{{$json.name}}` (webhook场景)	`{{$json.body.name}}`
`'={{$json.email}}'` (Code节点)	`$json.email`

Working Examples

实战示例

For real workflow examples, see EXAMPLES.md

真实工作流示例，请查看EXAMPLES.md

Example 1: Webhook to Slack

示例1：Webhook转Slack

Webhook receives:

json

{
  "body": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello!"
  }
}

In Slack node text field:

New form submission!

Name: {{$json.body.name}}
Email: {{$json.body.email}}
Message: {{$json.body.message}}

Webhook接收数据:

json

{
  "body": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello!"
  }
}

Slack节点文本字段内容:

新表单提交！

姓名: {{$json.body.name}}
邮箱: {{$json.body.email}}
留言: {{$json.body.message}}

Example 2: HTTP Request to Email

示例2：HTTP请求转邮件

HTTP Request returns:

json

{
  "data": {
    "items": [
      {"name": "Product 1", "price": 29.99}
    ]
  }
}

In Email node (reference HTTP Request):

Product: {{$node["HTTP Request"].json.data.items[0].name}}
Price: ${{$node["HTTP Request"].json.data.items[0].price}}

HTTP请求返回数据:

json

{
  "data": {
    "items": [
      {"name": "Product 1", "price": 29.99}
    ]
  }
}

邮件节点中（引用HTTP Request节点）:

产品: {{$node["HTTP Request"].json.data.items[0].name}}
价格: ${{$node["HTTP Request"].json.data.items[0].price}}

Example 3: Format Timestamp

示例3：时间戳格式化

javascript

// Current date
{{$now.toFormat('yyyy-MM-dd')}}
// Result: 2025-10-20

// Time
{{$now.toFormat('HH:mm:ss')}}
// Result: 14:30:45

// Full datetime
{{$now.toFormat('yyyy-MM-dd HH:mm')}}
// Result: 2025-10-20 14:30

javascript

// 当前日期
{{$now.toFormat('yyyy-MM-dd')}}
// 结果: 2025-10-20

// 当前时间
{{$now.toFormat('HH:mm:ss')}}
// 结果: 14:30:45

// 完整日期时间
{{$now.toFormat('yyyy-MM-dd HH:mm')}}
// 结果: 2025-10-20 14:30

Data Type Handling

数据类型处理

Arrays

数组

javascript

// First item
{{$json.users[0].email}}

// Array length
{{$json.users.length}}

// Last item
{{$json.users[$json.users.length - 1].name}}

javascript

// 第一个元素
{{$json.users[0].email}}

// 数组长度
{{$json.users.length}}

// 最后一个元素
{{$json.users[$json.users.length - 1].name}}

Objects

对象

javascript

// Dot notation (no spaces)
{{$json.user.email}}

// Bracket notation (with spaces or dynamic)
{{$json['user data'].email}}

javascript

// 点语法（无空格）
{{$json.user.email}}

// 括号语法（含空格或动态场景）
{{$json['user data'].email}}

Strings

字符串

javascript

// Concatenation (automatic)
Hello {{$json.name}}!

// String methods
{{$json.email.toLowerCase()}}
{{$json.name.toUpperCase()}}

javascript

// 自动拼接
Hello {{$json.name}}!

// 字符串方法
{{$json.email.toLowerCase()}}
{{$json.name.toUpperCase()}}

Numbers

数字

javascript

// Direct use
{{$json.price}}

// Math operations
{{$json.price * 1.1}}  // Add 10%
{{$json.quantity + 5}}

javascript

// 直接使用
{{$json.price}}

// 数学运算
{{$json.price * 1.1}}  // 加价10%
{{$json.quantity + 5}}

Advanced Patterns

高级用法模式

Conditional Content

条件内容

javascript

// Ternary operator
{{$json.status === 'active' ? 'Active User' : 'Inactive User'}}

// Default values
{{$json.email || 'no-email@example.com'}}

javascript

// 三元运算符
{{$json.status === 'active' ? '活跃用户' : '非活跃用户'}}

// 默认值
{{$json.email || 'no-email@example.com'}}

Date Manipulation

日期操作

javascript

// Add days
{{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}}

// Subtract hours
{{$now.minus({hours: 24}).toISO()}}

// Set specific date
{{DateTime.fromISO('2025-12-25').toFormat('MMMM dd, yyyy')}}

javascript

// 增加天数
{{$now.plus({days: 7}).toFormat('yyyy-MM-dd')}}

// 减少小时
{{$now.minus({hours: 24}).toISO()}}

// 设置指定日期
{{DateTime.fromISO('2025-12-25').toFormat('MMMM dd, yyyy')}}

String Manipulation

字符串操作

javascript

// Substring
{{$json.email.substring(0, 5)}}

// Replace
{{$json.message.replace('old', 'new')}}

// Split and join
{{$json.tags.split(',').join(', ')}}

javascript

// 子字符串
{{$json.email.substring(0, 5)}}

// 替换
{{$json.message.replace('old', 'new')}}

// 分割与拼接
{{$json.tags.split(',').join(', ')}}

Debugging Expressions

表达式调试

Test in Expression Editor

在表达式编辑器中测试

Click field with expression
Open expression editor (click "fx" icon)
See live preview of result
Check for errors highlighted in red

点击包含表达式的字段
打开表达式编辑器（点击"fx"图标）
查看结果实时预览
检查红色高亮的错误

Common Error Messages

常见错误提示

"Cannot read property 'X' of undefined" → Parent object doesn't exist → Check your data path

"X is not a function" → Trying to call method on non-function → Check variable type

Expression shows as literal text → Missing {{ }} → Add curly braces

"Cannot read property 'X' of undefined" → 父对象不存在 → 检查数据路径

"X is not a function" → 尝试对非函数调用方法 → 检查变量类型

表达式显示为纯文本 → 缺少{{ }} → 添加大括号

Expression Helpers

表达式辅助方法

Available Methods

可用方法

String:

```
.toLowerCase()
```
,
```
.toUpperCase()
```
```
.trim()
```
,
```
.replace()
```
,
```
.substring()
```
```
.split()
```
,
```
.includes()
```

Array:

```
.length
```
,
```
.map()
```
,
```
.filter()
```
```
.find()
```
,
```
.join()
```
,
```
.slice()
```

DateTime (Luxon):

```
.toFormat()
```
,
```
.toISO()
```
,
```
.toLocal()
```
```
.plus()
```
,
```
.minus()
```
,
```
.set()
```

Number:

```
.toFixed()
```
,
```
.toString()
```
Math operations:
```
+
```
,
```
-
```
,
```
*
```
,
```
/
```
,
```
%
```

字符串:

```
.toLowerCase()
```
,
```
.toUpperCase()
```
```
.trim()
```
,
```
.replace()
```
,
```
.substring()
```
```
.split()
```
,
```
.includes()
```

数组:

```
.length
```
,
```
.map()
```
,
```
.filter()
```
```
.find()
```
,
```
.join()
```
,
```
.slice()
```

日期时间（Luxon）:

```
.toFormat()
```
,
```
.toISO()
```
,
```
.toLocal()
```
```
.plus()
```
,
```
.minus()
```
,
```
.set()
```

数字:

```
.toFixed()
```
,
```
.toString()
```
数学运算:
```
+
```
,
```
-
```
,
```
*
```
,
```
/
```
,
```
%
```

Best Practices

最佳实践

✅ Do

✅ 建议

Always use {{ }} for dynamic content
Use bracket notation for field names with spaces
Reference webhook data from
```
.body
```
Use $node for data from other nodes
Test expressions in expression editor

动态内容始终使用{{ }}
含空格的字段名称使用括号语法
Webhook数据从
```
.body
```
中获取
使用$node引用其他节点的数据
在表达式编辑器中测试表达式

❌ Don't

❌ 不建议

Don't use expressions in Code nodes
Don't forget quotes around node names with spaces
Don't double-wrap with extra {{ }}
Don't assume webhook data is at root (it's under .body!)
Don't use expressions in webhook paths or credentials

Code节点中不使用表达式
带空格的节点名称不要忘记加引号
不要重复添加多余的{{ }}
不要默认认为Webhook数据在根层级（实际在.body下！）
Webhook路径或凭证字段中不使用表达式

Related Skills

Summary

总结

Essential Rules:

Wrap expressions in {{ }}
Webhook data is under
```
.body
```
No {{ }} in Code nodes
Quote node names with spaces
Node names are case-sensitive

Most Common Mistakes:

Missing {{ }} → Add braces
```
{{$json.name}}
```
in webhooks → Use
```
{{$json.body.name}}
```
```
{{$json.email}}
```
in Code → Use
```
$json.email
```

{{$node.HTTP Request}}

→ Use

{{$node["HTTP Request"]}}

For more details, see:

COMMON_MISTAKES.md - Complete error catalog
EXAMPLES.md - Real workflow examples

Need Help? Reference the n8n expression documentation or use n8n-mcp validation tools to check your expressions.

核心规则:

表达式用{{ }}包裹
Webhook数据在
```
.body
```
下
Code节点中不使用{{ }}
带空格的节点名称加引号
节点名称区分大小写

最常见错误:

缺少{{ }} → 添加大括号
Webhook场景中使用
```
{{$json.name}}
```
→ 改为
```
{{$json.body.name}}
```
Code节点中使用
```
{{$json.email}}
```
→ 改为
```
$json.email
```

使用

{{$node.HTTP Request}}

→ 改为

{{$node["HTTP Request"]}}

更多详情，请查看:

COMMON_MISTAKES.md - 完整错误目录
EXAMPLES.md - 真实工作流示例

需要帮助？ 参考n8n表达式文档，或使用n8n-mcp验证工具检查表达式。