# n8n Code 节点：JavaScript、Python、两种模式与常见错误 > n8n 的 Code 节点把你自己写的 JavaScript 或 Python 作为工作流的一步来运行。默认模式 Run Once for All Items 让代码对所有输入数据项只运行一次，Run Once for Each Item 则对每个数据项各运行一次。无论哪种模式，代码都必须返回带 json 键的对象，而且它不能发 HTTP 请求、读文件或使用凭据。 Mindket 编辑部 · 发布于 2026-11-04 · 更新于 2026-11-05 · https://mindket.com/cn/learn/n8n-advanced/n8n-code-node ## 要点 - 在 Run Once for All Items 和 Run Once for Each Item 之间选择，并按各自的格式返回数据。 - 在节点里用 $input、$json 和 $('节点名') 读取数据。 - 创建新数据项时，用 pairedItem 保持数据项之间的关联。 - 知道这个节点做不到什么，并看懂它常见的错误。 ## 开始之前 Code 节点在 2026 年的几次发布里变化不小，所以先确认你的版本。[文档](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code)说，它从 n8n 0.198.0 起取代了 Function 和 Function Item 节点。n8n 3.0 目前处于抢先体验阶段，它删掉了这两个旧节点。 [破坏性变更页面](https://docs.n8n.io/changelog/v30-breaking-changes)给出了对应关系：**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`，后面有一节会解释它： ````javascript // 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 页面](https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/output-to-the-browser-console)说，Code 节点里的 `console.log()` 会写到那里。 ## 两种模式，两种返回格式 n8n 在节点之间传递的数据是一个对象数组，每个对象把数据包在 `json` 键里。[数据结构页面](https://docs.n8n.io/build/work-with-data/understand-n8ns-data-structure)补充说，从 n8n 0.166.0 起，Code 节点会替你补上缺的 `json` 键和外面的数组，所以直接返回普通对象也行。把两者都写清楚，能让代码把返回的内容交代明白。 每种模式接受什么，由 JavaScript 任务运行器的[源码](https://github.com/n8n-io/n8n/blob/master/packages/@n8n/task-runner/src/js-task-runner/js-task-runner.ts)说了算。Run Once for Each Item 对每个输入项运行一次代码，并期望返回一个数据项。返回 `null` 会跳过这一项，n8n 会替你把 `pairedItem` 设成当前下标。下面是上面那个示例的逐项版本： ````javascript // Mode: Run Once for Each Item return { json: { name: $json.name, nameLength: $json.name.length } }; ```` | 方面 | Run Once for All Items | Run Once for Each Item | | --- | --- | --- | | 代码运行几次 | 只运行一次，不管来了多少输入项 | 每个输入项运行一次 | | 用什么读取输入 | `$input.all()`、`$input.first()`、`$input.last()` | `$input.item` 或 `$json` | | 返回什么 | 一个数据项数组 | 一个数据项 | | 返回 `null` | 没有数据项输出 | 跳过这一项 | | 数据项关联 | 新数据项要你自己设置 `pairedItem` | n8n 把 `pairedItem` 设成当前下标 | ## 从输入和其他节点读取数据 [引用页面](https://docs.n8n.io/build/work-with-data/reference-data/reference-previous-nodes)列出了 Code 节点里能用的写法。在编辑器里输入 `$`，n8n 会提示其余的。二进制数据有自己的规则：这里不能用 `$binary`，要调用 `this.helpers.getBinaryDataBuffer(itemIndex, binaryPropertyName)`，[Cookbook 页面](https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/get-the-binary-data-buffer)推荐它，而不是去碰 `items[0].binary.data.data`。Python 里不支持它。 表达式编辑器和 Code 节点之间有一个陷阱。[快捷方式页面](https://docs.n8n.io/build/code-in-n8n/use-built-in-shortcuts)说，Code 节点运行的是普通 JavaScript，用的是原生 Luxon，不是 n8n 的表达式引擎。 > **原生 Luxon，没有 n8n 的扩展** > > 表达式参考里标着 Custom n8n functionality 的功能，在这里可能不存在。DateTime.format() 就是一个，请改用 toFormat()。$if() 和 $jmespath() 这类顶层辅助函数只能在表达式编辑器里用。DateTime.plus() 和 minus() 只接受一个类似 Duration 的对象，比如 { days: 7 }，表达式里的 (amount, unit) 写法不会报错，但结果是错的。 | 写法 | 得到什么 | | --- | --- | | `$input.all()` | 所有输入数据项 | | `$input.first()`、`$input.last()` | 第一个或最后一个输入数据项 | | `$input.item` | 正在处理的数据项 | | `$json` | `$input.item.json` 的简写，逐项运行时可用 | | `$('节点名').all()`、`.first()`、`.last()` | 另一个节点的数据项，可选参数是 `branchIndex` 和 `runIndex` | | `$('节点名').item` | 那个节点里产生当前数据项的那一项 | | `$('节点名').itemMatching(i)` | 从输入项往回追溯时，用它代替 `.item` | | `$input.context.noItemsLeft` | 一个布尔值，只在 Loop Over Items 里才有 | ## Code 节点里的 Python 把 **Language** 设成 **Python**，用的就是任务运行器提供的原生 Python。[文档](https://docs.n8n.io/build/code-in-n8n/using-the-code-node)把从 Pyodide 迁移称为破坏性变更，所以旧脚本可能要改。下面是第一个示例的原生 Python 版本： ````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 自动处理关联。输入项不止一个时，你[添加或返回新数据项](https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/preserving-linking-in-the-code-node)就要自己提供关联，办法是把 `pairedItem` 设成输入项的下标。第一个示例里带着 `pairedItem: i`，原因就在这里。 往回追溯靠 `itemMatching`。下面是[文档里的示例](https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/accessing-linked-items-in-the-code-node)，它把被 Edit Fields 节点丢掉的邮箱地址找了回来： ````javascript 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 节点做不到什么 代码由任务运行器执行。[文档](https://docs.n8n.io/deploy/host-n8n/configure-n8n/set-up-task-runners)称它们是用户代码和 n8n 之间唯一的隔离层，说内部模式已被弃用，并要求生产实例使用外部模式，也就是在 n8n 旁边再放一个运行器容器。Docker 这一侧，[自托管那一课](https://mindket.com/cn/learn/n8n/self-host-n8n-docker)讲过。 超时也变了。[任务运行器变量页面](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/task-runners)仍把 `N8N_RUNNERS_TASK_TIMEOUT` 的默认值写成 300 秒，而破坏性变更把它降到了 60，所以运行超过一分钟的任务会失败，除非你自己设置这个变量。 **这些限制背后的三个数字** - **60** 在 n8n 3.0 里，Code 节点的任务最多能跑的秒数，原来是 300 (来源：[n8n Docs: v3.0 breaking changes](https://docs.n8n.io/changelog/v30-breaking-changes), 2026-11-05 查阅) - **2** n8n Cloud 允许 JavaScript 的 Code 节点导入的模块数，即 crypto 和 moment (来源：[n8n Docs: Code node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code), 2026-11-04 查阅) - **6.6k** n8n-skills 在 GitHub 上的星数，这套 Claude Code 技能里有两个专讲 Code 节点 (来源：[Romuald Członkowski on GitHub: n8n-skills](https://github.com/czlonkowski/n8n-skills), 2026-11-05 查阅) | 你想做的事 | Code 节点的情况 | 改用什么 | | --- | --- | --- | | 发 HTTP 请求 | 做不到 | HTTP Request 节点 | | 读写文件 | 做不到 | Read/Write Files from Disk 节点 | | 使用凭据 | 按设计就不行，`this.getCredentials()` 会报错 | 支持凭据的 HTTP Request 节点 | | 在自托管 n8n 上导入 npm 模块 | 默认被禁止，要先放行 | `NODE_FUNCTION_ALLOW_BUILTIN` 和 `NODE_FUNCTION_ALLOW_EXTERNAL`，使用任务运行器时设在运行器上 | | 在 n8n Cloud 上导入 npm 模块 | 不可能 | n8n 提供的两个模块：crypto 和 moment | ## n8n-skills 的作者和 Samir Saci 怎么说 Code 节点用什么语言 Romuald Członkowski 在华沙的 AiAdvisors 工作。他做的 [n8n-skills](https://github.com/czlonkowski/n8n-skills) 是一套用 Claude Code 搭 n8n 工作流的技能。它的 Python 技能给的建议很直接：95% 的场景都用 JavaScript。所以 Code 节点默认用 JavaScript 写，Python 留给已经放行了所需模块的自托管实例。 它列出的理由，和上面讲 Python 的那一节对得上：原生 Python 只能用 `_items` 或 `_item`，按字典方式取值。而且除非实例把模块加进白名单，否则所有 import 都会被拦下，n8n Cloud 上一个都不放行。 2025 年 10 月，n8n 团队[在 X 上推荐了 Samir Saci 的文章](https://x.com/n8n_io/status/1973659279413403874)。自称 LogiGreen 创始人的 Saci 讲了在 n8n 里从 Python 转到 JavaScript，用 Code 节点做销售分析，画 ABC 和帕累托图。这类分析要一次读到所有行，所以移植时用 Run Once for All Items 模式。 > 95% 的场景都用 JavaScript > > Romuald Członkowski, n8n-skills 的作者，AiAdvisors，引文为译文, [GitHub](https://github.com/czlonkowski/n8n-skills) (2026-11-05 查阅) [![n8n.io（@n8n_io）2025 年 10 月 2 日在 X 上的帖子：推荐 @Samir_Saci_ 的一篇好文章，讲在 n8n 里从 Python 转到 JavaScript。他演示了怎样用 Code 节点做销售分析、画 ABC 和帕累托图，并和 FastAPI 做对比。](https://mindket.com/blog/shots/x-n8n-io-python-to-javascript.webp?v=7c6964f43e0a)](https://x.com/n8n_io/status/1973659279413403874) n8n.io 在 X 上，2025 年 10 月 2 日 > X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。点击截图可到 X 上打开原帖。 ## 常见错误 - "Code doesn't return items properly" 和 "Code doesn't return an object"。节点必须返回一个对象数组，每个对象把数据包在 `json` 里。脚本末尾没有 `return`，或者返回了 `undefined`，都会掉进这里，[常见问题页面](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/common-issues)有解释。 - "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](https://docs.n8n.io/changelog/v30-breaking-changes) 把它从 JavaScript 的 Code 节点里删了，而安全模式的运行器，也就是 n8n 2.0 起的默认模式，本来就会在它上面失败。请在前一个节点的某个字段里计算表达式，再读取结果。 - 让节点处理超大数据。[内存页面](https://docs.n8n.io/deploy/host-n8n/configure-n8n/scaling/fix-memory-issues)在降低内存消耗的建议里写了“尽量避免使用 Code 节点”。 ## 自己试一试 - 先跑全部数据项的示例，再用同一份输入跑逐项的示例，比较输出的数据项。 - 在逐项的示例里，对没有 `name` 的数据项返回 `null`，数一数输出了多少项。 - 加上 `console.log($input.first())`，运行节点时查看浏览器控制台。 - 如果你是自托管，用 `NODE_FUNCTION_ALLOW_BUILTIN=crypto` 放行一个内置模块，用 `require()` 加载它，给某个字段做哈希。 ## 接下来学什么 Code 节点跑在任务运行器上，规模化部署时每个 worker 都需要自己的运行器。[第 4 课](https://mindket.com/cn/learn/n8n-advanced/n8n-queue-mode)把 n8n 切换到队列模式，用上 Redis、worker，以及决定同时能跑多少任务的那些设置。想在写代码之前先了解 n8n 的节点能做什么，可以从[什么是 n8n](https://mindket.com/cn/blog/what-is-n8n)开始。 ## 自测一下 1. 你用的是 Run Once for Each Item。代码应该返回什么？ A. 一个数据项数组 B. 一个数据项，比如 { json: { ... } } C. 一个普通字符串 答案：B。 逐项模式对每个输入项运行一次代码，并期望返回一个数据项，返回 null 则跳过这一项。 2. Code 节点接触不到凭据。哪个节点可以发起需要认证的 API 调用？ A. Edit Fields B. Read/Write Files from Disk C. Execute Sub-workflow D. HTTP Request 答案：D。 HTTP Request 节点支持凭据，而 Code 节点按设计就访问不了凭据。 3. 在 Code 节点的原生 Python 里，怎样读取输入项的 name 字段？ A. item["json"]["name"] B. item.json.name C. $json.name 答案：A。 原生 Python 只接受方括号访问，点号写法属于已被淘汰的 Pyodide 版本。 4. 在 Run Once for All Items 模式下，你创建了新数据项，后面的节点要能追溯到它们。你要在每个数据项上设置什么？ A. binary B. itemMatching C. pairedItem 答案：C。 新数据项不关联任何输入，除非你把 pairedItem 设成输入项的下标。 ## 常见问题 ### n8n 的 Code 节点能发 HTTP 请求吗？ 不能。文档说，在 Code 节点里不能访问文件系统，也不能发 HTTP 请求。请用同样支持凭据的 HTTP Request 节点，以及 Read/Write Files from Disk 节点。 ### Code 节点里能用 npm 包吗？ 在自托管的 n8n 上能，要先用 NODE_FUNCTION_ALLOW_BUILTIN 和 NODE_FUNCTION_ALLOW_EXTERNAL 放行。使用外部任务运行器时，要设在运行器上。在 n8n Cloud 上不能导入外部模块，只有 crypto 和 moment 可用。 ### 能在 Code 节点里导入 Python 库吗？ n8n Cloud 上不行，那里的 Python 选项完全不允许导入。自托管的用户可以把库加进 n8nio/runners 镜像并加入白名单，文档还说，n8n 团队承诺长期会让用户在任务运行器上安全地使用任意库。 ### 升级后，旧的 Function 节点还能运行吗？ 不能。用了已删除节点的工作流运行时会失败，已发布的工作流在 n8n 启动时不会激活，触发器也就不再触发。升级之前，Settings 里的 Migration Report 会列出受影响的工作流。 ### 为什么 Code 节点报关于 json 的错？ 节点期望得到一个对象数组，数据放在 json 键下，而这个键必须是对象。n8n 会替你补上缺的 json 键和外层数组，但 json 被设成数组时仍然会失败。 ### 怎样调试 Code 节点里的代码？ 在 JavaScript 里用 console.log()，在 Python 里用 print()，然后打开浏览器的开发者控制台并运行节点。原生 Python 里可以直接打印 `_items` 或 `_item`。 ## 资料来源 - [n8n Docs: Code node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code) (2026-11-04 查阅) - [n8n Docs: Using the Code node](https://docs.n8n.io/build/code-in-n8n/using-the-code-node) (2026-11-04 查阅) - [n8n Docs: Code node common issues](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/common-issues) (2026-11-04 查阅) - [n8n Docs: Enable modules in Code node](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/enable-modules-in-code-node) (2026-11-04 查阅) - [n8n Docs: Understand n8n's data structure](https://docs.n8n.io/build/work-with-data/understand-n8ns-data-structure) (2026-11-04 查阅) - [n8n Docs: Reference previous nodes](https://docs.n8n.io/build/work-with-data/reference-data/reference-previous-nodes) (2026-11-04 查阅) - [n8n Docs: Use built-in shortcuts](https://docs.n8n.io/build/code-in-n8n/use-built-in-shortcuts) (2026-11-04 查阅) - [n8n Docs: Output to the browser console](https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/output-to-the-browser-console) (2026-11-04 查阅) - [n8n Docs: Get the binary data buffer](https://docs.n8n.io/build/code-in-n8n/cookbook/code-node/get-the-binary-data-buffer) (2026-11-04 查阅) - [n8n Docs: Accessing linked items in the Code node](https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/accessing-linked-items-in-the-code-node) (2026-11-04 查阅) - [n8n Docs: Preserving linking in the Code node](https://docs.n8n.io/build/work-with-data/reference-data/link-data-items/preserving-linking-in-the-code-node) (2026-11-04 查阅) - [n8n Docs: Set up task runners](https://docs.n8n.io/deploy/host-n8n/configure-n8n/set-up-task-runners) (2026-11-04 查阅) - [n8n Docs: Task runner environment variables](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/use-environment-variables/task-runners) (2026-11-04 查阅) - [n8n Docs: Fix memory issues](https://docs.n8n.io/deploy/host-n8n/configure-n8n/scaling/fix-memory-issues) (2026-11-04 查阅) - [n8n Docs: v3.0 breaking changes](https://docs.n8n.io/changelog/v30-breaking-changes) (2026-11-05 查阅) - [n8n repository: JavaScript task runner (js-task-runner.ts)](https://github.com/n8n-io/n8n/blob/master/packages/@n8n/task-runner/src/js-task-runner/js-task-runner.ts) (2026-11-04 查阅) - [Romuald Członkowski on GitHub: n8n-skills](https://github.com/czlonkowski/n8n-skills) (2026-11-05 查阅) - [n8n.io on X: great post by Samir Saci on moving from Python to JavaScript in n8n, 2 October 2025](https://x.com/n8n_io/status/1973659279413403874) (2026-11-05 查阅) [浏览 n8n 工作流](https://mindket.com/cn/automations/n8n)