n8n-expression-syntax

n8n 表达式语法

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

执行与数据范围

下文和指南中提到的 EXAMPLES.md 和 COMMON_MISTAKES.md 未随附。表达式参数中的 $json 表示当前输入项，而不是当前节点已完成的输出；引用其他节点前，请检查实际执行数据和项链接。Code 节点 API 在逐项模式和所有项模式下有所不同。请使用凭据存储机密：指南中的 $env 示例可能会泄露值，也可能处于禁用状态。避免在消息或日志中放入机密或个人 Webhook 数据。对 URL 路径和查询组件进行编码，防范数组或对象缺失的情况，并在下游操作前验证不受信任的值。使用合成输入测试表达式；预览成功不代表已获准发送 Slack/电子邮件消息。

详细指南

执行此技能前，请阅读详细指南。其中保留了完整的流程和参考资料。必须遵守其中的安全要求、前置条件和验证要求。针对特定任务，请加载相关章节；端到端工作则应完整阅读指南。

适用场景

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

---

不要使用表达式的场景

❌ Code 节点

Code 节点使用直接 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();

❌ Webhook 路径

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

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

❌ 凭据字段

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

// ✅ CORRECT
Use n8n credential system, not expressions

---

示例

真实工作流示例请参见 EXAMPLES.md

示例 1：Webhook 到 Slack

Webhook 接收到：

{
  "body": {
    "name": "John Doe",
    "email": "[email protected]",
    "message": "Hello!"
  }
}

在 Slack 节点的文本字段中：

New form submission!

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

示例 2：HTTP Request 到电子邮件

HTTP Request 返回：

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

在 Email 节点中（引用 HTTP Request）：

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

示例 3：格式化时间戳

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

---

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。