n8n-syntax-code-node 是 n8n v1.x Code 节点的完整参考,用于在编写 JavaScript 或 Python 模式的 Code 节点逻辑时查阅语法、变量、限制与返回格式。
用途 该技能面向需要在 n8n 工作流中编写 Code 节点逻辑的场景,帮助避免运行时错误与常见误用。
语言与执行模式 JavaScript(Node.js)始终可用;Python 需设置 N8N_PYTHON_ENABLED=true(稳定版 v1.111.0+)。默认模式为「Run Once for All Items」。选择模式时可参考决策树:独立处理条目(过滤、转换、补充)用「Run Once for Each Item」;跨全部条目比较或聚合(排序、去重、汇总)用默认的「Run Once for All Items」;若原生节点可完成则优先使用原生节点。
返回格式 「Run Once for All Items」必须返回 [{json: {...}}] 数组;「Run Once for Each Item」返回单个 {json: {...}} 对象。不得返回不带 json 包装的原始数据。
五项关键限制 所有 Code 节点执行均受限制:禁止文件系统访问(不用 fs、path,改用 Read/Write Files From Disk 节点);禁止 HTTP 请求(不用 fetch、axios、http,改用 HTTP Request 节点);不可使用 $itemIndex(需手动维护循环计数器);不可访问 $secrets(需通过前置节点输出传递);不可使用 $parameter(需硬编码或作为输入数据传入)。
可用变量 JavaScript 侧提供 items、$input.item、$input.all()、$input.first()、$input.last()、$json、$binary、$("<node>").all()/first()/itemMatching(i)、$execution、$workflow、$now、$today、$env、$vars、$prevNode、$runIndex、$jmespath、$ifEmpty、$getWorkflowStaticData 等。Python 使用下划线前缀对应变量(如 _items、_item、_input),且必须使用方括号取值,如 item["json"]["field"]。
二进制数据 JavaScript 可用 this.helpers.getBinaryDataBuffer() 读取,用 prepareBinaryData 构造二进制条目;Python 不支持 getBinaryDataBuffer()。不得直接访问 items[0].binary.data.data。
内置模块 Node.js crypto 与 moment 在云端和自托管均可用;Luxon 通过表达式使用;外部 npm 模块仅自托管且需环境配置。n8n Cloud 上不得导入外部库。
条目关联与错误处理 在 Code 节点中追踪条目应使用 $("<node>").itemMatching(index),而非 $("<node>").item。可用 try-catch 将错误作为数据返回以让工作流继续。
不宜使用的场景 过滤、字段设置、排序、去重、限制数量、拆分数组、合并数据、日期格式化、简单条件判断应优先使用对应原生节点,因原生节点更快且自动维护条目关联。
参考文件 随附 references/methods.md(变量、模块、返回格式)、references/examples.md(JS 与 Python 模式示例)、references/anti-patterns.md(常见错误与修正)。