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}}

访问环境变量：

javascript

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

🚨 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 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();

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

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 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

2. 带空格的名称需加引号

Field or node names with spaces require bracket notation:

javascript

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

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

字段或节点名称带空格时，需使用方括号写法：

javascript

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

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

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}}'` (代码节点)	`$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

代码节点中不要使用表达式
带空格的节点名称不要忘记加引号
不要重复添加多余的{{ }}
不要默认认为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
```
下
代码节点中不要使用{{ }}
带空格的节点名称需加引号
节点名称区分大小写

最常见错误:

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

使用

{{$node.HTTP Request}}

→ 改为

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

更多详情，请查看：

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

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