n8n Code 节点：JavaScript、Python、两种模式与常见错误

开始之前

Code 节点在 2026 年的几次发布里变化不小，所以先确认你的版本。文档说，它从 n8n 0.198.0 起取代了 Function 和 Function Item 节点。n8n 3.0 目前处于抢先体验阶段，它删掉了这两个旧节点。

破坏性变更页面给出了对应关系：Run Once for All Items 取代 Function，Run Once for Each Item 取代 Function Item。同一个版本还去掉了 Ask AI 标签，用它生成过的代码会留在节点里继续运行。

Python 也变了。旧的 Pyodide 版本在 n8n 2.0 里被删除，基于任务运行器的原生 Python 从 n8n 1.111.0 开始提供，到 n8n 2 已经稳定。本课的示例是我们自己写的，依据文档里的变量名和数据项结构。

写第一个 Code 节点

从节点出去的每个数据项，都是带 json 键的对象。下面的示例用每个输入项的 name 字段生成新数据项，并设置了 pairedItem，后面有一节会解释它：

// Mode: Run Once for All Items
const rows = $input.all();
const out = [];
for (let i = 0; i < rows.length; i++) {
  out.push({
    json: { name: rows[i].json.name, nameLength: rows[i].json.name.length },
    pairedItem: i,
  });
}
return out;

1. 在一个输出带 name 字段数据项的节点后面添加 Code 节点，比如 Edit Fields 节点。
2. 把 Language 设为 JavaScript，Mode 设为 Run Once for All Items，这是默认值。
3. 把示例粘贴进代码编辑器。
4. 选择 Execute step。输出里每个输入项对应一个数据项，每个都有 name 和 nameLength。
5. 在 return 上面加一行 console.log(rows.length)，再运行一次节点，并打开浏览器的开发者控制台。Cookbook 页面说，Code 节点里的 console.log() 会写到那里。

两种模式，两种返回格式

n8n 在节点之间传递的数据是一个对象数组，每个对象把数据包在 json 键里。数据结构页面补充说，从 n8n 0.166.0 起，Code 节点会替你补上缺的 json 键和外面的数组，所以直接返回普通对象也行。把两者都写清楚，能让代码把返回的内容交代明白。

每种模式接受什么，由 JavaScript 任务运行器的源码说了算。Run Once for Each Item 对每个输入项运行一次代码，并期望返回一个数据项。返回 null 会跳过这一项，n8n 会替你把 pairedItem 设成当前下标。下面是上面那个示例的逐项版本：

// Mode: Run Once for Each Item
return { json: { name: $json.name, nameLength: $json.name.length } };

从输入和其他节点读取数据

引用页面列出了 Code 节点里能用的写法。在编辑器里输入 $，n8n 会提示其余的。二进制数据有自己的规则：这里不能用 $binary，要调用 this.helpers.getBinaryDataBuffer(itemIndex, binaryPropertyName)，Cookbook 页面推荐它，而不是去碰 items[0].binary.data.data。Python 里不支持它。

表达式编辑器和 Code 节点之间有一个陷阱。快捷方式页面说，Code 节点运行的是普通 JavaScript，用的是原生 Luxon，不是 n8n 的表达式引擎。

Code 节点里的 Python

把 Language 设成 Python，用的就是任务运行器提供的原生 Python。文档把从 Pyodide 迁移称为破坏性变更，所以旧脚本可能要改。下面是第一个示例的原生 Python 版本：

# Mode: Run Once for All Items, native Python
rows = []
for item in _items:
    rows.append({"json": {"name": item["json"]["name"]}})
return rows

• 只有全部数据项模式下的 _items 和逐项模式下的 _item。n8n 的其他内置方法和变量都不支持。
• 字段要用方括号访问，比如 item["json"]["my_new_field"]。点号写法 item.json.myNewField 不被接受。
• 在自托管的 n8n 上，只有 n8nio/runners 镜像包含并加入白名单的标准库和第三方模块才能导入。在 n8n Cloud 上，完全不允许导入。
• 不安全的内置函数默认被禁用，type() 就在名单里。想查看数据，请用 print(_items)。

保持数据项关联不丢

大多数节点会把每个输出项关联到产生它的输入项，后面的节点用 $('节点名').item 沿着这条链往回找。在 Code 节点里，只有一个数据项时 n8n 自动处理关联。输入项不止一个时，你添加或返回新数据项就要自己提供关联，办法是把 pairedItem 设成输入项的下标。第一个示例里带着 pairedItem: i，原因就在这里。

往回追溯靠 itemMatching。下面是文档里的示例，它把被 Edit Fields 节点丢掉的邮箱地址找了回来：

for(let i=0; i<$input.all().length; i++) {
	$input.all()[i].json.restoreEmail = $('Customer Datastore (n8n training)').itemMatching(i).json.email;
}
return $input.all();

Code 节点做不到什么

代码由任务运行器执行。文档称它们是用户代码和 n8n 之间唯一的隔离层，说内部模式已被弃用，并要求生产实例使用外部模式，也就是在 n8n 旁边再放一个运行器容器。Docker 这一侧，自托管那一课讲过。

超时也变了。任务运行器变量页面仍把 N8N_RUNNERS_TASK_TIMEOUT 的默认值写成 300 秒，而破坏性变更把它降到了 60，所以运行超过一分钟的任务会失败，除非你自己设置这个变量。

n8n-skills 的作者和 Samir Saci 怎么说 Code 节点用什么语言

Romuald Członkowski 在华沙的 AiAdvisors 工作。他做的 n8n-skills 是一套用 Claude Code 搭 n8n 工作流的技能。它的 Python 技能给的建议很直接：95% 的场景都用 JavaScript。所以 Code 节点默认用 JavaScript 写，Python 留给已经放行了所需模块的自托管实例。

它列出的理由，和上面讲 Python 的那一节对得上：原生 Python 只能用 _items 或 _item，按字典方式取值。而且除非实例把模块加进白名单，否则所有 import 都会被拦下，n8n Cloud 上一个都不放行。

2025 年 10 月，n8n 团队在 X 上推荐了 Samir Saci 的文章。自称 LogiGreen 创始人的 Saci 讲了在 n8n 里从 Python 转到 JavaScript，用 Code 节点做销售分析，画 ABC 和帕累托图。这类分析要一次读到所有行，所以移植时用 Run Once for All Items 模式。

X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。点击截图可到 X 上打开原帖。

常见错误

• "Code doesn't return items properly" 和 "Code doesn't return an object"。节点必须返回一个对象数组，每个对象把数据包在 json 里。脚本末尾没有 return，或者返回了 undefined，都会掉进这里，常见问题页面有解释。
• "A 'json' property isn't an object"。你把 json 设成了数组。把数组放进一个对象里，比如 { json: { rows } }。
• "'import' and 'export' may only appear at the top level"。沙箱不支持它们，请改用 require()，在自托管上还要先放行这个模块。
• "Cannot find module"。把模块安装进你的 n8n 环境，用 Docker 的话要扩展官方镜像。然后设置 NODE_FUNCTION_ALLOW_BUILTIN 或 NODE_FUNCTION_ALLOW_EXTERNAL。使用外部任务运行器时，要改在运行器的配置文件里设置。
• 调用 $getCredentials() 或 this.getCredentials()。按设计就会失败，把需要认证的调用挪到 HTTP Request 节点里。
• 调用 $evaluateExpression()。n8n 3.0 把它从 JavaScript 的 Code 节点里删了，而安全模式的运行器，也就是 n8n 2.0 起的默认模式，本来就会在它上面失败。请在前一个节点的某个字段里计算表达式，再读取结果。
• 让节点处理超大数据。内存页面在降低内存消耗的建议里写了“尽量避免使用 Code 节点”。

自己试一试

• 先跑全部数据项的示例，再用同一份输入跑逐项的示例，比较输出的数据项。
• 在逐项的示例里，对没有 name 的数据项返回 null，数一数输出了多少项。
• 加上 console.log($input.first())，运行节点时查看浏览器控制台。
• 如果你是自托管，用 NODE_FUNCTION_ALLOW_BUILTIN=crypto 放行一个内置模块，用 require() 加载它，给某个字段做哈希。

接下来学什么

Code 节点跑在任务运行器上，规模化部署时每个 worker 都需要自己的运行器。第 4 课把 n8n 切换到队列模式，用上 Redis、worker，以及决定同时能跑多少任务的那些设置。想在写代码之前先了解 n8n 的节点能做什么，可以从什么是 n8n开始。

常见问题

资料来源

1. n8n Docs: Code node (2026年11月4日 查阅)https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code
2. n8n Docs: Using the Code node (2026年11月4日 查阅)https://docs.n8n.io/build/code-in-n8n/using-the-code-node
3. n8n Docs: Code node common issues (2026年11月4日 查阅)https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/common-issues
4. n8n Docs: Enable modules in Code node (2026年11月4日 查阅)https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/enable-modules-in-code-node
5. n8n Docs: Understand n8n's data structure (2026年11月4日 查阅)https://docs.n8n.io/build/work-with-data/understand-n8ns-data-structure
6. n8n Docs: Reference previous nodes (2026年11月4日 查阅)https://docs.n8n.io/build/work-with-data/reference-data/reference-previous-nodes
7. n8n Docs: Use built-in shortcuts (2026年11月4日 查阅)https://docs.n8n.io/build/code-in-n8n/use-built-in-shortcuts
8. n8n Docs: Output to the browser console (2026年11月4日 查阅)https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/output-to-the-browser-console
9. n8n Docs: Get the binary data buffer (2026年11月4日 查阅)https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/get-the-binary-data-buffer
10. n8n Docs: Accessing linked items in the Code node (2026年11月4日 查阅)https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/accessing-linked-items-in-the-code-node
11. n8n Docs: Preserving linking in the Code node (2026年11月4日 查阅)https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/preserving-linking-in-the-code-node
12. n8n Docs: Set up task runners (2026年11月4日 查阅)https://docs.n8n.io/deploy/host-n8n/configure-n8n/set-up-task-runners
13. n8n Docs: Task runner environment variables (2026年11月4日 查阅)https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/task-runners
14. n8n Docs: Fix memory issues (2026年11月4日 查阅)https://docs.n8n.io/deploy/host-n8n/configure-n8n/scaling/fix-memory-issues
15. n8n Docs: v3.0 breaking changes (2026年11月5日 查阅)https://docs.n8n.io/changelog/v30-breaking-changes
16. n8n repository: JavaScript task runner (js-task-runner.ts) (2026年11月4日 查阅)https://github.com/n8n-io/n8n/blob/master/packages/@n8n/task-runner/src/js-task-runner/js-task-runner.ts
17. Romuald Członkowski on GitHub: n8n-skills (2026年11月5日 查阅)https://github.com/czlonkowski/n8n-skills
18. n8n.io on X: great post by Samir Saci on moving from Python to JavaScript in n8n, 2 October 2025 (2026年11月5日 查阅)https://x.com/n8n_io/status/1973659279413403874