作为一个经常拿 n8n 当业务中台用的老玩家我得先说实话很多人把 n8n 当成一个拉积木工具靠粘贴节点把流程串起来就完事了。但真到生产环境里跑一阵子你就会发现最卡脖子的根本不是节点怎么连而是代码节点Code Node会不会写。什么复杂字段重命名、多层嵌套 JSON 拍平、跨系统数据关联、请求体动态拼接这些靠纯图形节点能绕但绕出来的流程丑得没法维护。这篇文章我打算把 n8n 代码节点的机制、写法、调试方法以及我在实际项目里踩过的坑一次说清楚。读完你至少能做到拿到一个 Webhook 或者 API 返回的乱七八糟数据知道怎么在代码节点里快速加工成下游要的格式并且能避开那些本地好好的、一上生产就挂的经典问题。也会简单提一下本地部署环境怎么搭因为代码节点写起来有个能随手跑的工作流环境比啥都重要。1. 为什么说代码节点是 n8n 工作流的真正分水岭很多初学者看到 n8n 的节点库就兴奋觉得这工具什么都能干根本不用写代码。这话对了一半。n8n 的图形节点确实覆盖了 HTTP 请求、数据库读写、邮件发送、文件处理这些高频动作但一旦遇到需要在传输过程中改写数据的场景图形节点就会变得非常笨拙。1.1 图形节点解决不了的三种麻烦第一种是结构转换。上游 Webhook 推给你的数据往往是一个嵌套 JSON里面的字段名跟你内部系统完全对不上甚至还包着一层无意义的对象例如{data:{list:[{id:a1,name:测试}]}}。你要把data.list里的每一项取出来、改名、再塞到下游能识别的结构里。用图形节点做就要拆成 JSON 解析、Item List 操作、改名、再聚合好几个节点每个节点都要小心配置中间任何一步结构理解错了就白干。第二种是跨节点数据的实时计算。比如你要对一组订单记录做同一天内订单金额的累加占比或者按客户 ID 去重找最新一条记录。这类聚合逻辑用 Set、Filter、Aggregate 节点能拼但拼出来的流程别人根本看不懂而且性能很拉胯。第三种是动态请求体拼装。你要根据用户传来的参数决定调用哪个外部接口、传什么 body还可能有多种分支参数组合。图形节点的表达式虽然能拼但一旦条件多了表达式套娃会套到你怀疑人生。1.2 一个例子看清内置节点和代码节点的差距我举个真实场景。某天业务方要求从 CRM 接口拉回客户列表过滤掉status为closed的客户把full_name拆成first_name和last_name再按region分组后给每个分组加一个从 1 开始的序号。用纯图形节点你需要HTTP Request 拉数据 → Code 节点解析不对如果不用 Code那就要用 JSON Parse → Filter 过滤 → Set 拆分字段 → Sort 排序 → Aggregate 分组……光是拆full_name这个动作在图形节点里就非常别扭得用表达式函数。整个流程至少六七个节点而且只要业务方说一句序号要按客户等级排你又得重插两个节点。同样的逻辑在代码节点里 30 行就结束const customers $input.all(); const seen new Map(); const output []; for (const item of customers) { const c item.json; if (c.status closed) continue; const [first, last] (c.full_name || ).split( ); const key c.region || unknown; const seq (seen.get(key) || 0) 1; seen.set(key, seq); output.push({ json: { first_name: first, last_name: last, region: key, seq } }); } return output;这段代码没有任何高深技巧就是普通 JavaScript。你只要会写基础循环和对象操作就能把那些要拖半天的节点流程压缩成一个代码节点。而且后续要改逻辑也只需要在这个节点里改几行代码不用在画布上到处找节点。1.3 代码节点适合谁来学如果你只是拿 n8n 连几个现成 API、传个 Webhook那可能暂时用不上代码节点。但只要你开始用 n8n 做正经项目——比如对接 ERP、处理订单、同步用户数据——代码节点就是必须掌握的技能。它本身不复杂难点反而在于你对 JavaScript 基础类型和异步处理的理解。我会在后面把 n8n 代码节点独特的运行机制讲清楚这是网上很多教程没说透的部分。2. 先把本地调试环境搭起来Docker 部署与配置我自己最早是在 Windows 上用 npm 全局安装跑 n8n 的后来换了 Docker 就没再回头。因为 n8n 在 Windows 上直接跑偶尔会遇到sqlite文件锁或者环境变量不一致的问题Docker 部署更干净升级也方便一条命令拉新镜像完事。这里就基于 Docker 讲。2.1 最简部署命令先保证机器上装了 Docker 和 Docker Compose。没有 docker-compose 的话一条 docker run 命令也能跑docker run -d \ --name n8n \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ -e GENERIC_TIMEZONEAsia/Shanghai \ -e TZAsia/Shanghai \ -e N8N_SECURE_COOKIEfalse \ n8nio/n8n:latest-v n8n_data:/home/node/.n8n是数据持久化必须加不然后面升级镜像你的工作流全没了。N8N_SECURE_COOKIEfalse是本地调试时让 HTTP 协议也能正常登录如果你准备用 HTTPS 反向代理那可以去掉。跑完之后访问http://localhost:5678首次进入会让你创建管理员账号。2.2 安装方式选型对比不同部署方式各有适用场景我看过不少同事从 npm 装起后来被迫迁到 Docker。这里给个直接对比安装方式适用场景优点需要留意的地方Docker / Docker Compose个人开发机、长期稳定运行的公网服务器环境隔离、升级方便、备份目录固定服务器上要懂一点 Docker 运维npm 全局安装本机快速体验、已经在用 Node.js 的场景命令简单n8n start就能起依赖 Node 版本升级容易残留旧包Windows 安装包完全不想碰命令行双击安装有桌面入口后台服务管理不透明路径常遇到权限问题n8n Cloud不想自己维护团队小规模跑省心、自动备份按量付费长期用不便宜如果你要跑正式业务我建议直接上 Docker Compose把挂载目录、端口、环境变量都写进 YAML 文件里换机器时整个配置靠一份文件就能重建。2.3 中文语言配置与常用环境变量n8n 官方界面的语言包是逐步补齐的现阶段很多中文用户会直接找汉化方案。比较常见的是通过环境变量指定语言文件或者在部署时替换前端的翻译 JSON。我自己在用的方式是在 Docker 里挂载一个自定义翻译文件通过N8N_DEFAULT_LOCALEzh来切换界面语言。不过 n8n 版本升级频繁自定义翻译文件偶尔会跟新版本的前端资源对不上建议先跑通一个测试环境确认无误后再上生产。部署完成后有几个环境变量是非常值得提前设置的N8N_PORT默认 5678如果端口被占可以改。N8N_ENCRYPTION_KEY用于加密 credentials建议固定填写一段随机字符串不然容器重建后已有的 credential 可能无法解密。EXECUTIONS_DATA_PRUNE默认开启指定执行记录保留时间避免数据库无限膨胀。WEBHOOK_URL如果你要通过公网接收 Webhook需要设置为实际对外地址。这些配置里最容易忽略的就是N8N_ENCRYPTION_KEY我亲眼见过有人升级容器后所有凭据都解密失败只能重新填。这一点务必一开始就写进 docker-compose。环境跑起来了下面正式进入代码节点的核心。3. 代码节点的核心机制Item、$input 与 returnn8n 的代码节点用的是 JavaScript但它跟你在 Node.js 或者浏览器里写普通脚本不太一样。最关键的区别就是它有一套自己定义的数据上下文你要先理解 Item 是什么、$input给到的是什么、return出去的又是什么否则写出来的代码经常没数据或者下游收不到。3.1 Item 到底是什么n8n 的整个工作流本质上就是处理一个JSON 对象数组。每次节点执行完成输出的都是[{ json: {...} }, { json: {...} }, ...]这样的结构里面每个{ json: {...} }就是一个 Item。所以你在代码节点里看到的$input.all()、$input.first()返回的不是裸数据而是这些 Item 对象。很多第一次写的人会直接写$input.all().name然后报错 undefined。正确做法是$input.all()[0].json.name因为name藏在每个 Item 的json字段里。这个结构和 n8n 的数据流界面是一致的你在画布上点开一个节点看到的每一个独立卡片就是一个 Item。3.2 代码节点常用的内建对象n8n 代码节点默认注入了一些全局对象常用的有这么几个$input表示当前节点的输入数据。它有几个方法$input.all()返回全部 Item 数组$input.first()返回第一个 Item$input.item是在为每个 Item 单独执行模式下当前的那个 Item。$json当前 Item 的 json 内容相当于$input.item.json。$node可以获取指定节点的输出例如$node[HTTP Request].json拿到上一个 HTTP 节点的输出但要注意选择数据面和方法。$execution获取当前执行任务的元信息比如$execution.id拿到执行 ID$execution.mode判断是 test 还是 production。getWorkflowStaticData()获取工作流的静态持久化数据可以在多次执行之间保存一些简单状态比如一个计数器。还有一个容易混淆的点代码节点的设置里有为每个传入 Item 执行一次和对所有 Item 执行一次两个模式。如果你选前者代码末尾return { json: ... }是处理一个 Item选后者时你可以返回一个包含多个 Item 的数组。理解这个配置能避免后面出现结果少了一条或者重复处理的问题。3.3 一个标准代码模板的逐行拆解下面这段代码可以当模板用我逐行解释// 1. 拿到所有输入 Item const items $input.all(); // 2. 创建一个数组存放处理后的数据 const results []; // 3. 遍历每一个 Item for (const item of items) { // 4. item.json 才是真正业务数据 const raw item.json; // 5. 在这里对 raw 做任何处理 const newItem { id: raw.userId, name: ${raw.firstName} ${raw.lastName}, createdAt: new Date(raw.timestamp).toISOString(), }; // 6. 标准化 n8n 的输出格式{ json: ... } results.push({ json: newItem }); } // 7. 返回数组 return results;第 4 步是最重要的认知转换item.json才是真实业务数据其他像item.binary之类的字段一般不需要管。第 6 步把处理结果重新包回{ json: ... }这步漏了你后面接其他节点就会看到fieldxxxdoes not exist的报错。如果你选了为每个传入 Item 执行一次代码可以更简洁const raw $json; return { json: { name: raw.name.toUpperCase() } };因为这种情况下 n8n 已经帮你把当前 Item 的 json 塞到了$json变量里。3.4 返回单个对象还是数组代码节点的返回值可以是一个单一对象return { json: {...} }一个数组return [{ json: {...} }, { json: {...} }]要注意的是如果你在处理单个 Item 的模式下返回数组n8n 会把它当作多个输出相当于这个 Item 被展开成多条这其实是一个很常用的技巧。比如一个客户关联了多个订单你想把一个客户记录扩展成多个客户-订单记录就可以在代码里返回一个数组。不过我在生产里踩过一个坑如果你返回return [];空数组下游节点会继承不到数据而且流程不会报错只是静默结束。如果业务上明确要求没有数据时也要发个通知就需要在代码节点里特殊处理比如手动推一个{ json: { empty: true } }或者接一个 IF 节点来判空。4. 实战拆解五个高频数据处理场景的写法理论说再多不如直接上真实业务里的代码块。我整理了五个我在项目里用得最多的场景全部可以直接抄。4.1 把嵌套 JSON 拍平成表格数据外部接口返回的经常是这种多层嵌套结构{ code: 0, data: { list: [ { id: 1, attrs: { color: red, size: L } }, { id: 2, attrs: { color: blue, size: M } } ] } }下游 MySQL 节点或者 Google Sheets 节点需要的是平铺的一行一条。代码节点里这样处理const body $json; // 假设当前 Item 是整个响应体 const list body.data.list || []; return list.map((item) ({ json: { id: item.id, color: item.attrs.color, size: item.attrs.size } }));注意我对body.data.list做了空值兜底防止接口返回异常时整个代码节点抛错。真实环境里接口字段经常说变就变任何访问嵌套对象的操作都建议给个默认值。4.2 根据关联 ID 合并两个输入源的数据n8n 工作流里经常需要把两个接口的数据关联起来。比如一份来自 MySQL 的用户表一份来自 CRM 的客户等级表它们之间有共同的customerId。代码节点可以直接做内存级 JOINconst users $input.all().map((i) i.json); // 假设通过 $node 拿到了另一个节点的输出 const crmData $node[CRM 查询].all(); const crmMap new Map( crmData.map((i) [i.json.customerId, i.json.level]) ); const results users.map((user) ({ json: { ...user, level: crmMap.get(user.customerId) || unknown } })); return results;用Map构建查找表比在循环里一层层find高效很多。数据量到几千条时find的性能差异就非常明显了而Map构建和查询都快得多。我在处理过几万条订单时就因为这个优化把单次执行时间从十几秒压到了两秒内。4.3 批量筛选重命名字段有时你只需要从一堆字段里挑出有用的并且把接口字段名改成内部命名规范。用 Set 节点能改但是字段一多就很啰嗦。代码节点里就是一次映射const items $input.all(); const fieldMap { user_name: username, email_address: email, mobile_phone: phone }; const output []; for (const item of items) { const old item.json; const newItem {}; for (const [oldKey, newKey] of Object.entries(fieldMap)) { if (old[oldKey] ! undefined) { newItem[newKey] old[oldKey]; } } output.push({ json: newItem }); } return output;这里有个经验不要用 JSON.stringify 和 JSON.parse 来深拷贝对象。有时候你会想这么做来避免引用污染但在代码节点里数据量一旦大了这个操作又慢又占内存。直接构建新的对象字面量或者用{ ...old }扩展运算符就好。4.4 根据条件动态拼接请求体在代码节点里生成下一个 HTTP 请求的 body是 n8n 里很常见的组合打法。你可以在代码节点末尾输出一个对象然后 HTTP Request 节点直接用表达式引用const raw $json; const baseBody { app_id: 12345, timestamp: Math.floor(Date.now() / 1000) }; if (raw.type create) { baseBody.action create; baseBody.data { title: raw.title, content: raw.content }; } else if (raw.type update) { baseBody.action update; baseBody.data { id: raw.id, title: raw.title }; } else { throw new Error(不支持的类型: ${raw.type}); } return { json: baseBody };看到那个throw new Error了吗这是代码节点的一个杀手锏。你在代码里主动抛异常工作流会立刻把这个执行标记为失败并且错误信息会显示在执行记录里。这样比返回一个奇怪的对象然后让下游节点懵掉要直观得多。4.5 聚合统计求和、去重、分组假设你要算一下一个批次订单的总金额按支付方式分组看看占比。这种逻辑放代码节点里就是普通 JavaScriptconst orders $input.all().map((i) i.json); const stats orders.reduce((acc, order) { const method order.payment_method || unknown; if (!acc[method]) { acc[method] { count: 0, total: 0 }; } acc[method].count 1; acc[method].total Number(order.amount) || 0; return acc; }, {}); const summary Object.keys(stats) .map((method) ({ json: { payment_method: method, order_count: stats[method].count, total_amount: stats[method].total } })) .sort((a, b) b.json.total_amount - a.json.total_amount); return summary;这里有用到Number(order.amount) || 0的兜底是因为字符串金额、空字符串、null 混在一起的情况我遇到过太多次了。排序是按金额降序方便下游直接做报表。5. 性能与避坑代码节点最常见的六类问题代码节点本身不难难点在隐藏的问题。下面这些每一次都是我用线上事故换回来的。5.1 不要在循环里同步请求外部接口不熟悉 JavaScript 异步的人很容易这样写for (const item of items) { const resp await fetch(https://api.example.com/xxx); // ... }n8n 代码节点在一个工作流执行里对第三方 API 并不是完全禁止异步但如果你在循环里挨个await fetch执行时间会变成所有请求的串行之和。数据量一大整个工作流的耗时直接爆炸而且容易触发外部服务的限流。正确做法是能批量接口就用批量接口实在不行最多用Promise.all并发控制而且一定要限制并发数量const concurrencyLimit 5; async function run() { const results []; const queue items.slice(); async function worker() { while (queue.length) { const item queue.shift(); const resp await fetch(item.url); results.push(await resp.json()); } } const workers Array.from({ length: concurrencyLimit }).map(() worker()); await Promise.all(workers); return results.map((r) ({ json: r })); } return run();这段代码用固定数量的 worker 循环取任务既能并发请求又不会一口气把所有请求打出去是我在代码节点里最常用的并法。5.2 对象属性为空时直接调方法导致崩溃item.name.toUpperCase()这种写法遇到name是null或者undefined时直接抛错。在代码节点里的错误提示往往很抽象只告诉你Cannot read properties of undefined不细心的话根本不知道是哪个字段出了问题。我的习惯是所有从外部接口拿到的字段在进入逻辑前先做一次规范化const name (raw.name || ).toString().trim(); const age Number(raw.age) || 0; const tags Array.isArray(raw.tags) ? raw.tags : [];这样后续的逻辑就不会被脏数据打断。5.3 返回结构不对导致下游节点找不到字段这是新手最容易犯的错。你直接在代码节点里return { name: sarah };然后下游节点引用{{ $json.name }}永远取不到。原因前面说了n8n 要求每条数据以{ json: ... }形式包裹。一旦返回格式不对你在编辑器里不会立刻看到报错因为代码节点本身算执行成功只有下游节点报字段缺失才暴露问题。所以请记住这个公式代码节点返回值 数组数组里每一项 { json: 业务数据 }。5.4 没搞懂为每个 Item 执行和针对整个输入执行的区别这个模式选错了行为差异很大而且出错时不容易看出来。选了为每个传入 Item 执行你的代码会被 n8n 对每条 Item 调用一次$json就是当前 Item。如果你代码里又用$input.all()取全部数据那每条 Item 处理时都会重新取一次全部性能开销成倍增加。选了对所有传入 Item 执行一次代码只跑一次你必须自己遍历处理所有 Item不能直接return { json: ... }返回单条除非你只想输出一条。我的建议是需要保持全局状态比如统计、去重、排序时用所有 Item 执行一次只是简单逐条转换字段时用每个 Item 执行一次。每条执行一次的代码简洁但别在里面做重复的全量取数。5.5 console.log 打出来的日志去哪了代码节点里写console.log是很重要的调试手段因为 n8n 编辑器不像浏览器控制台那样直接弹出日志。你可以点开右侧的执行选项卡展开代码节点日志会显示在输出数据卡片下方你也能在节点设置里打开输出面板查看 console 输出。还有一个小技巧想快速看某个中间值可以直接return { json: { debug: result } }把它当输出验证完再删。说实话这种方式比开日志更直观。5.6 凭据和密码不要硬编码在代码里很多人图省事在代码节点里直接写const apiKey sk-xxxx;这非常危险。工作流导出分享或者被人看到截图密钥就直接泄了。n8n 有内置的 Credentials 机制你可以创建一个 Header Auth 或者 Generic Credential Type在 HTTP Request 节点里引用。如果你非要在代码节点里用可以通过环境变量注入然后用process.env.MY_SECRET读取。这也是为什么我前面强调部署时要用N8N_ENCRYPTION_KEY和正确的环境变量管理方式安全底线不能省。6. 进阶玩法代码节点结合外部 API 与工作流状态代码节点不只是加工数据的管道它还能当执行引擎用。下面几个进阶用法能让你对 n8n 的掌控力大幅提升。6.1 需要时才请求外部服务比如你的工作流整体是个调度任务根据不同的输入条件只有少数时候需要调用一个第三方计费接口。你可以在代码节点里判断需要时才发请求const raw $json; if (raw.needCharge ! true) { return { json: { skipped: true } }; } const resp await fetch(https://billing.example.com/charge, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ userId: raw.userId, amount: raw.amount }) }); if (!resp.ok) { throw new Error(计费接口失败: ${resp.status} (await resp.text())); } return { json: { charged: true, txId: (await resp.json()).txId } };注意我在resp.ok false的路径里主动抛错这样 n8n 会把这次执行标记为失败便于告警。如果只是记一条日志然后继续往下走也可以不抛错返回一个{ error: ... }结构然后在后面接一个 IF 节点分流。哪种方式合适取决于你的业务是否需要失败快速暴露。这个选择最好在项目初期定好不然十几个工作流的错误处理风格会非常混乱。6.2 读取工作流执行状态代码节点里可以用$execution拿到当前执行的相关信息比如return { json: { executionId: $execution.id, mode: $execution.mode, startedAt: new Date().toISOString() } };这个在重跑报错、排查问题的时候很有用。我还试过把这个执行 ID 写到数据库表里方便下游出问题后回溯原始数据。配一个 Webhook 接口把执行日志回传出来基本就是一个简陋的可观测平台了。6.3 利用静态数据保存状态n8n 的getWorkflowStaticData()可以在同一工作流的多次执行之间保存 JSON 化的数据。假设你要做上次同步的游标或者每日累计计数器用它就够const staticData getWorkflowStaticData(); // 初始化 if (!staticData.lastSyncTime) { staticData.lastSyncTime 0; } // 本次增量查询时间范围 const startTime staticData.lastSyncTime; const now Date.now(); staticData.lastSyncTime now; return { json: { startTime, endTime: now } };这个静态数据不会因为执行结束而清空会保存在 n8n 的工作流数据中。不过要注意它依赖单个工作流实例如果你用队列执行器或者多个工作流并行改同一份静态数据可能会有并发问题。生产环境里更稳的做法还是把状态存到外部 Redis 或者数据库静态数据适合轻量自用。6.4 代码节点的包导入限制默认情况下n8n 代码节点并不允许任意require(第三方包)。它允许的是 n8n 内部暴露的n8n/相关工具和一些内置模块第三方包需要在构建自定义镜像时预装。如果你真的需要在代码节点里用类似lodash这样的库最实际的办法是构建一个自定义 Docker 镜像FROM n8nio/n8n:latest RUN npm install -g lodash然后你在代码节点里require(lodash)才能生效。不过我个人不推荐为了用库去改镜像绝大多数业务逻辑用原生 JavaScript 就能写而且原生代码的调试思路更直观不依赖某个工具的独特语法。真遇到复杂到必须引入第三方库的逻辑我一般建议拆出去做成单独微服务。7. 我整理的一套代码节点开发习惯最后聊聊经验和习惯。代码节点写到后面你会发现真正决定维护体验的不是语法而是你长期的编码习惯。命名规则。工作流里会有很多代码节点我习惯给每个节点命名成能看懂它输出是什么的名字比如代码节点-标准化订单数据、代码节点-按客户分组统计。别就叫Code Node等你有二十个工作流之后光看节点列表就会崩溃。注释要写业务意图不是复述代码。比如// 这里把接口的状态码翻译成内部字段是有效注释// 循环遍历items是废话。团队协作时代码注释的价值在于让下一个接手的人知道为什么这样写而不只是写了什么。建议建一个公共工作流模板库。把高频用到的代码节点存成模板比如Webhook Body 自动拍平、错误统一包装返回、分页拉取接口数据团队新成员可以直接复制。这比每个人从零想实现方式要稳得多。留意执行记录里的耗时。n8n 执行页面会记录每个节点的耗时如果你发现某个代码节点执行了十几秒一定要警惕是不是在循环里同步请求了是不是重复取全量数据了很多时候光是把$input.all()从循环里提出来耗时就大幅下降。还有一个我踩过不少次的小坑在为每个 Item 执行模式下使用$input.all()你不光性能受损还可能因为引用同一个数组导致逻辑混乱。这时候优先用$json或者$input.item把关注点放在当前这条数据上。另外如果你准备把 n8n 用到企业级代码节点的版本控制最好也纳入 git。工作流本身导出为 JSON 文件代码节点的内容都在这份 JSON 里。你完全可以定期把工作流 JSON 备份到仓库代码节点的重要修改留痕出问题的时候回滚才不慌。说到底代码节点就是把你从图形节点的限制里解放出来的那个口子。它让我用 n8n 搭建工作流的时候不再是一个被固定组件框住的拼图工而是一个真正在写代码、控制数据流的开发者。希望这篇文章能帮你少走一些弯路把精力花在真正有价值的业务逻辑上。
n8n代码节点实战指南：从调试机制到高效数据处理技巧
作为一个经常拿 n8n 当业务中台用的老玩家我得先说实话很多人把 n8n 当成一个拉积木工具靠粘贴节点把流程串起来就完事了。但真到生产环境里跑一阵子你就会发现最卡脖子的根本不是节点怎么连而是代码节点Code Node会不会写。什么复杂字段重命名、多层嵌套 JSON 拍平、跨系统数据关联、请求体动态拼接这些靠纯图形节点能绕但绕出来的流程丑得没法维护。这篇文章我打算把 n8n 代码节点的机制、写法、调试方法以及我在实际项目里踩过的坑一次说清楚。读完你至少能做到拿到一个 Webhook 或者 API 返回的乱七八糟数据知道怎么在代码节点里快速加工成下游要的格式并且能避开那些本地好好的、一上生产就挂的经典问题。也会简单提一下本地部署环境怎么搭因为代码节点写起来有个能随手跑的工作流环境比啥都重要。1. 为什么说代码节点是 n8n 工作流的真正分水岭很多初学者看到 n8n 的节点库就兴奋觉得这工具什么都能干根本不用写代码。这话对了一半。n8n 的图形节点确实覆盖了 HTTP 请求、数据库读写、邮件发送、文件处理这些高频动作但一旦遇到需要在传输过程中改写数据的场景图形节点就会变得非常笨拙。1.1 图形节点解决不了的三种麻烦第一种是结构转换。上游 Webhook 推给你的数据往往是一个嵌套 JSON里面的字段名跟你内部系统完全对不上甚至还包着一层无意义的对象例如{data:{list:[{id:a1,name:测试}]}}。你要把data.list里的每一项取出来、改名、再塞到下游能识别的结构里。用图形节点做就要拆成 JSON 解析、Item List 操作、改名、再聚合好几个节点每个节点都要小心配置中间任何一步结构理解错了就白干。第二种是跨节点数据的实时计算。比如你要对一组订单记录做同一天内订单金额的累加占比或者按客户 ID 去重找最新一条记录。这类聚合逻辑用 Set、Filter、Aggregate 节点能拼但拼出来的流程别人根本看不懂而且性能很拉胯。第三种是动态请求体拼装。你要根据用户传来的参数决定调用哪个外部接口、传什么 body还可能有多种分支参数组合。图形节点的表达式虽然能拼但一旦条件多了表达式套娃会套到你怀疑人生。1.2 一个例子看清内置节点和代码节点的差距我举个真实场景。某天业务方要求从 CRM 接口拉回客户列表过滤掉status为closed的客户把full_name拆成first_name和last_name再按region分组后给每个分组加一个从 1 开始的序号。用纯图形节点你需要HTTP Request 拉数据 → Code 节点解析不对如果不用 Code那就要用 JSON Parse → Filter 过滤 → Set 拆分字段 → Sort 排序 → Aggregate 分组……光是拆full_name这个动作在图形节点里就非常别扭得用表达式函数。整个流程至少六七个节点而且只要业务方说一句序号要按客户等级排你又得重插两个节点。同样的逻辑在代码节点里 30 行就结束const customers $input.all(); const seen new Map(); const output []; for (const item of customers) { const c item.json; if (c.status closed) continue; const [first, last] (c.full_name || ).split( ); const key c.region || unknown; const seq (seen.get(key) || 0) 1; seen.set(key, seq); output.push({ json: { first_name: first, last_name: last, region: key, seq } }); } return output;这段代码没有任何高深技巧就是普通 JavaScript。你只要会写基础循环和对象操作就能把那些要拖半天的节点流程压缩成一个代码节点。而且后续要改逻辑也只需要在这个节点里改几行代码不用在画布上到处找节点。1.3 代码节点适合谁来学如果你只是拿 n8n 连几个现成 API、传个 Webhook那可能暂时用不上代码节点。但只要你开始用 n8n 做正经项目——比如对接 ERP、处理订单、同步用户数据——代码节点就是必须掌握的技能。它本身不复杂难点反而在于你对 JavaScript 基础类型和异步处理的理解。我会在后面把 n8n 代码节点独特的运行机制讲清楚这是网上很多教程没说透的部分。2. 先把本地调试环境搭起来Docker 部署与配置我自己最早是在 Windows 上用 npm 全局安装跑 n8n 的后来换了 Docker 就没再回头。因为 n8n 在 Windows 上直接跑偶尔会遇到sqlite文件锁或者环境变量不一致的问题Docker 部署更干净升级也方便一条命令拉新镜像完事。这里就基于 Docker 讲。2.1 最简部署命令先保证机器上装了 Docker 和 Docker Compose。没有 docker-compose 的话一条 docker run 命令也能跑docker run -d \ --name n8n \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ -e GENERIC_TIMEZONEAsia/Shanghai \ -e TZAsia/Shanghai \ -e N8N_SECURE_COOKIEfalse \ n8nio/n8n:latest-v n8n_data:/home/node/.n8n是数据持久化必须加不然后面升级镜像你的工作流全没了。N8N_SECURE_COOKIEfalse是本地调试时让 HTTP 协议也能正常登录如果你准备用 HTTPS 反向代理那可以去掉。跑完之后访问http://localhost:5678首次进入会让你创建管理员账号。2.2 安装方式选型对比不同部署方式各有适用场景我看过不少同事从 npm 装起后来被迫迁到 Docker。这里给个直接对比安装方式适用场景优点需要留意的地方Docker / Docker Compose个人开发机、长期稳定运行的公网服务器环境隔离、升级方便、备份目录固定服务器上要懂一点 Docker 运维npm 全局安装本机快速体验、已经在用 Node.js 的场景命令简单n8n start就能起依赖 Node 版本升级容易残留旧包Windows 安装包完全不想碰命令行双击安装有桌面入口后台服务管理不透明路径常遇到权限问题n8n Cloud不想自己维护团队小规模跑省心、自动备份按量付费长期用不便宜如果你要跑正式业务我建议直接上 Docker Compose把挂载目录、端口、环境变量都写进 YAML 文件里换机器时整个配置靠一份文件就能重建。2.3 中文语言配置与常用环境变量n8n 官方界面的语言包是逐步补齐的现阶段很多中文用户会直接找汉化方案。比较常见的是通过环境变量指定语言文件或者在部署时替换前端的翻译 JSON。我自己在用的方式是在 Docker 里挂载一个自定义翻译文件通过N8N_DEFAULT_LOCALEzh来切换界面语言。不过 n8n 版本升级频繁自定义翻译文件偶尔会跟新版本的前端资源对不上建议先跑通一个测试环境确认无误后再上生产。部署完成后有几个环境变量是非常值得提前设置的N8N_PORT默认 5678如果端口被占可以改。N8N_ENCRYPTION_KEY用于加密 credentials建议固定填写一段随机字符串不然容器重建后已有的 credential 可能无法解密。EXECUTIONS_DATA_PRUNE默认开启指定执行记录保留时间避免数据库无限膨胀。WEBHOOK_URL如果你要通过公网接收 Webhook需要设置为实际对外地址。这些配置里最容易忽略的就是N8N_ENCRYPTION_KEY我亲眼见过有人升级容器后所有凭据都解密失败只能重新填。这一点务必一开始就写进 docker-compose。环境跑起来了下面正式进入代码节点的核心。3. 代码节点的核心机制Item、$input 与 returnn8n 的代码节点用的是 JavaScript但它跟你在 Node.js 或者浏览器里写普通脚本不太一样。最关键的区别就是它有一套自己定义的数据上下文你要先理解 Item 是什么、$input给到的是什么、return出去的又是什么否则写出来的代码经常没数据或者下游收不到。3.1 Item 到底是什么n8n 的整个工作流本质上就是处理一个JSON 对象数组。每次节点执行完成输出的都是[{ json: {...} }, { json: {...} }, ...]这样的结构里面每个{ json: {...} }就是一个 Item。所以你在代码节点里看到的$input.all()、$input.first()返回的不是裸数据而是这些 Item 对象。很多第一次写的人会直接写$input.all().name然后报错 undefined。正确做法是$input.all()[0].json.name因为name藏在每个 Item 的json字段里。这个结构和 n8n 的数据流界面是一致的你在画布上点开一个节点看到的每一个独立卡片就是一个 Item。3.2 代码节点常用的内建对象n8n 代码节点默认注入了一些全局对象常用的有这么几个$input表示当前节点的输入数据。它有几个方法$input.all()返回全部 Item 数组$input.first()返回第一个 Item$input.item是在为每个 Item 单独执行模式下当前的那个 Item。$json当前 Item 的 json 内容相当于$input.item.json。$node可以获取指定节点的输出例如$node[HTTP Request].json拿到上一个 HTTP 节点的输出但要注意选择数据面和方法。$execution获取当前执行任务的元信息比如$execution.id拿到执行 ID$execution.mode判断是 test 还是 production。getWorkflowStaticData()获取工作流的静态持久化数据可以在多次执行之间保存一些简单状态比如一个计数器。还有一个容易混淆的点代码节点的设置里有为每个传入 Item 执行一次和对所有 Item 执行一次两个模式。如果你选前者代码末尾return { json: ... }是处理一个 Item选后者时你可以返回一个包含多个 Item 的数组。理解这个配置能避免后面出现结果少了一条或者重复处理的问题。3.3 一个标准代码模板的逐行拆解下面这段代码可以当模板用我逐行解释// 1. 拿到所有输入 Item const items $input.all(); // 2. 创建一个数组存放处理后的数据 const results []; // 3. 遍历每一个 Item for (const item of items) { // 4. item.json 才是真正业务数据 const raw item.json; // 5. 在这里对 raw 做任何处理 const newItem { id: raw.userId, name: ${raw.firstName} ${raw.lastName}, createdAt: new Date(raw.timestamp).toISOString(), }; // 6. 标准化 n8n 的输出格式{ json: ... } results.push({ json: newItem }); } // 7. 返回数组 return results;第 4 步是最重要的认知转换item.json才是真实业务数据其他像item.binary之类的字段一般不需要管。第 6 步把处理结果重新包回{ json: ... }这步漏了你后面接其他节点就会看到fieldxxxdoes not exist的报错。如果你选了为每个传入 Item 执行一次代码可以更简洁const raw $json; return { json: { name: raw.name.toUpperCase() } };因为这种情况下 n8n 已经帮你把当前 Item 的 json 塞到了$json变量里。3.4 返回单个对象还是数组代码节点的返回值可以是一个单一对象return { json: {...} }一个数组return [{ json: {...} }, { json: {...} }]要注意的是如果你在处理单个 Item 的模式下返回数组n8n 会把它当作多个输出相当于这个 Item 被展开成多条这其实是一个很常用的技巧。比如一个客户关联了多个订单你想把一个客户记录扩展成多个客户-订单记录就可以在代码里返回一个数组。不过我在生产里踩过一个坑如果你返回return [];空数组下游节点会继承不到数据而且流程不会报错只是静默结束。如果业务上明确要求没有数据时也要发个通知就需要在代码节点里特殊处理比如手动推一个{ json: { empty: true } }或者接一个 IF 节点来判空。4. 实战拆解五个高频数据处理场景的写法理论说再多不如直接上真实业务里的代码块。我整理了五个我在项目里用得最多的场景全部可以直接抄。4.1 把嵌套 JSON 拍平成表格数据外部接口返回的经常是这种多层嵌套结构{ code: 0, data: { list: [ { id: 1, attrs: { color: red, size: L } }, { id: 2, attrs: { color: blue, size: M } } ] } }下游 MySQL 节点或者 Google Sheets 节点需要的是平铺的一行一条。代码节点里这样处理const body $json; // 假设当前 Item 是整个响应体 const list body.data.list || []; return list.map((item) ({ json: { id: item.id, color: item.attrs.color, size: item.attrs.size } }));注意我对body.data.list做了空值兜底防止接口返回异常时整个代码节点抛错。真实环境里接口字段经常说变就变任何访问嵌套对象的操作都建议给个默认值。4.2 根据关联 ID 合并两个输入源的数据n8n 工作流里经常需要把两个接口的数据关联起来。比如一份来自 MySQL 的用户表一份来自 CRM 的客户等级表它们之间有共同的customerId。代码节点可以直接做内存级 JOINconst users $input.all().map((i) i.json); // 假设通过 $node 拿到了另一个节点的输出 const crmData $node[CRM 查询].all(); const crmMap new Map( crmData.map((i) [i.json.customerId, i.json.level]) ); const results users.map((user) ({ json: { ...user, level: crmMap.get(user.customerId) || unknown } })); return results;用Map构建查找表比在循环里一层层find高效很多。数据量到几千条时find的性能差异就非常明显了而Map构建和查询都快得多。我在处理过几万条订单时就因为这个优化把单次执行时间从十几秒压到了两秒内。4.3 批量筛选重命名字段有时你只需要从一堆字段里挑出有用的并且把接口字段名改成内部命名规范。用 Set 节点能改但是字段一多就很啰嗦。代码节点里就是一次映射const items $input.all(); const fieldMap { user_name: username, email_address: email, mobile_phone: phone }; const output []; for (const item of items) { const old item.json; const newItem {}; for (const [oldKey, newKey] of Object.entries(fieldMap)) { if (old[oldKey] ! undefined) { newItem[newKey] old[oldKey]; } } output.push({ json: newItem }); } return output;这里有个经验不要用 JSON.stringify 和 JSON.parse 来深拷贝对象。有时候你会想这么做来避免引用污染但在代码节点里数据量一旦大了这个操作又慢又占内存。直接构建新的对象字面量或者用{ ...old }扩展运算符就好。4.4 根据条件动态拼接请求体在代码节点里生成下一个 HTTP 请求的 body是 n8n 里很常见的组合打法。你可以在代码节点末尾输出一个对象然后 HTTP Request 节点直接用表达式引用const raw $json; const baseBody { app_id: 12345, timestamp: Math.floor(Date.now() / 1000) }; if (raw.type create) { baseBody.action create; baseBody.data { title: raw.title, content: raw.content }; } else if (raw.type update) { baseBody.action update; baseBody.data { id: raw.id, title: raw.title }; } else { throw new Error(不支持的类型: ${raw.type}); } return { json: baseBody };看到那个throw new Error了吗这是代码节点的一个杀手锏。你在代码里主动抛异常工作流会立刻把这个执行标记为失败并且错误信息会显示在执行记录里。这样比返回一个奇怪的对象然后让下游节点懵掉要直观得多。4.5 聚合统计求和、去重、分组假设你要算一下一个批次订单的总金额按支付方式分组看看占比。这种逻辑放代码节点里就是普通 JavaScriptconst orders $input.all().map((i) i.json); const stats orders.reduce((acc, order) { const method order.payment_method || unknown; if (!acc[method]) { acc[method] { count: 0, total: 0 }; } acc[method].count 1; acc[method].total Number(order.amount) || 0; return acc; }, {}); const summary Object.keys(stats) .map((method) ({ json: { payment_method: method, order_count: stats[method].count, total_amount: stats[method].total } })) .sort((a, b) b.json.total_amount - a.json.total_amount); return summary;这里有用到Number(order.amount) || 0的兜底是因为字符串金额、空字符串、null 混在一起的情况我遇到过太多次了。排序是按金额降序方便下游直接做报表。5. 性能与避坑代码节点最常见的六类问题代码节点本身不难难点在隐藏的问题。下面这些每一次都是我用线上事故换回来的。5.1 不要在循环里同步请求外部接口不熟悉 JavaScript 异步的人很容易这样写for (const item of items) { const resp await fetch(https://api.example.com/xxx); // ... }n8n 代码节点在一个工作流执行里对第三方 API 并不是完全禁止异步但如果你在循环里挨个await fetch执行时间会变成所有请求的串行之和。数据量一大整个工作流的耗时直接爆炸而且容易触发外部服务的限流。正确做法是能批量接口就用批量接口实在不行最多用Promise.all并发控制而且一定要限制并发数量const concurrencyLimit 5; async function run() { const results []; const queue items.slice(); async function worker() { while (queue.length) { const item queue.shift(); const resp await fetch(item.url); results.push(await resp.json()); } } const workers Array.from({ length: concurrencyLimit }).map(() worker()); await Promise.all(workers); return results.map((r) ({ json: r })); } return run();这段代码用固定数量的 worker 循环取任务既能并发请求又不会一口气把所有请求打出去是我在代码节点里最常用的并法。5.2 对象属性为空时直接调方法导致崩溃item.name.toUpperCase()这种写法遇到name是null或者undefined时直接抛错。在代码节点里的错误提示往往很抽象只告诉你Cannot read properties of undefined不细心的话根本不知道是哪个字段出了问题。我的习惯是所有从外部接口拿到的字段在进入逻辑前先做一次规范化const name (raw.name || ).toString().trim(); const age Number(raw.age) || 0; const tags Array.isArray(raw.tags) ? raw.tags : [];这样后续的逻辑就不会被脏数据打断。5.3 返回结构不对导致下游节点找不到字段这是新手最容易犯的错。你直接在代码节点里return { name: sarah };然后下游节点引用{{ $json.name }}永远取不到。原因前面说了n8n 要求每条数据以{ json: ... }形式包裹。一旦返回格式不对你在编辑器里不会立刻看到报错因为代码节点本身算执行成功只有下游节点报字段缺失才暴露问题。所以请记住这个公式代码节点返回值 数组数组里每一项 { json: 业务数据 }。5.4 没搞懂为每个 Item 执行和针对整个输入执行的区别这个模式选错了行为差异很大而且出错时不容易看出来。选了为每个传入 Item 执行你的代码会被 n8n 对每条 Item 调用一次$json就是当前 Item。如果你代码里又用$input.all()取全部数据那每条 Item 处理时都会重新取一次全部性能开销成倍增加。选了对所有传入 Item 执行一次代码只跑一次你必须自己遍历处理所有 Item不能直接return { json: ... }返回单条除非你只想输出一条。我的建议是需要保持全局状态比如统计、去重、排序时用所有 Item 执行一次只是简单逐条转换字段时用每个 Item 执行一次。每条执行一次的代码简洁但别在里面做重复的全量取数。5.5 console.log 打出来的日志去哪了代码节点里写console.log是很重要的调试手段因为 n8n 编辑器不像浏览器控制台那样直接弹出日志。你可以点开右侧的执行选项卡展开代码节点日志会显示在输出数据卡片下方你也能在节点设置里打开输出面板查看 console 输出。还有一个小技巧想快速看某个中间值可以直接return { json: { debug: result } }把它当输出验证完再删。说实话这种方式比开日志更直观。5.6 凭据和密码不要硬编码在代码里很多人图省事在代码节点里直接写const apiKey sk-xxxx;这非常危险。工作流导出分享或者被人看到截图密钥就直接泄了。n8n 有内置的 Credentials 机制你可以创建一个 Header Auth 或者 Generic Credential Type在 HTTP Request 节点里引用。如果你非要在代码节点里用可以通过环境变量注入然后用process.env.MY_SECRET读取。这也是为什么我前面强调部署时要用N8N_ENCRYPTION_KEY和正确的环境变量管理方式安全底线不能省。6. 进阶玩法代码节点结合外部 API 与工作流状态代码节点不只是加工数据的管道它还能当执行引擎用。下面几个进阶用法能让你对 n8n 的掌控力大幅提升。6.1 需要时才请求外部服务比如你的工作流整体是个调度任务根据不同的输入条件只有少数时候需要调用一个第三方计费接口。你可以在代码节点里判断需要时才发请求const raw $json; if (raw.needCharge ! true) { return { json: { skipped: true } }; } const resp await fetch(https://billing.example.com/charge, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ userId: raw.userId, amount: raw.amount }) }); if (!resp.ok) { throw new Error(计费接口失败: ${resp.status} (await resp.text())); } return { json: { charged: true, txId: (await resp.json()).txId } };注意我在resp.ok false的路径里主动抛错这样 n8n 会把这次执行标记为失败便于告警。如果只是记一条日志然后继续往下走也可以不抛错返回一个{ error: ... }结构然后在后面接一个 IF 节点分流。哪种方式合适取决于你的业务是否需要失败快速暴露。这个选择最好在项目初期定好不然十几个工作流的错误处理风格会非常混乱。6.2 读取工作流执行状态代码节点里可以用$execution拿到当前执行的相关信息比如return { json: { executionId: $execution.id, mode: $execution.mode, startedAt: new Date().toISOString() } };这个在重跑报错、排查问题的时候很有用。我还试过把这个执行 ID 写到数据库表里方便下游出问题后回溯原始数据。配一个 Webhook 接口把执行日志回传出来基本就是一个简陋的可观测平台了。6.3 利用静态数据保存状态n8n 的getWorkflowStaticData()可以在同一工作流的多次执行之间保存 JSON 化的数据。假设你要做上次同步的游标或者每日累计计数器用它就够const staticData getWorkflowStaticData(); // 初始化 if (!staticData.lastSyncTime) { staticData.lastSyncTime 0; } // 本次增量查询时间范围 const startTime staticData.lastSyncTime; const now Date.now(); staticData.lastSyncTime now; return { json: { startTime, endTime: now } };这个静态数据不会因为执行结束而清空会保存在 n8n 的工作流数据中。不过要注意它依赖单个工作流实例如果你用队列执行器或者多个工作流并行改同一份静态数据可能会有并发问题。生产环境里更稳的做法还是把状态存到外部 Redis 或者数据库静态数据适合轻量自用。6.4 代码节点的包导入限制默认情况下n8n 代码节点并不允许任意require(第三方包)。它允许的是 n8n 内部暴露的n8n/相关工具和一些内置模块第三方包需要在构建自定义镜像时预装。如果你真的需要在代码节点里用类似lodash这样的库最实际的办法是构建一个自定义 Docker 镜像FROM n8nio/n8n:latest RUN npm install -g lodash然后你在代码节点里require(lodash)才能生效。不过我个人不推荐为了用库去改镜像绝大多数业务逻辑用原生 JavaScript 就能写而且原生代码的调试思路更直观不依赖某个工具的独特语法。真遇到复杂到必须引入第三方库的逻辑我一般建议拆出去做成单独微服务。7. 我整理的一套代码节点开发习惯最后聊聊经验和习惯。代码节点写到后面你会发现真正决定维护体验的不是语法而是你长期的编码习惯。命名规则。工作流里会有很多代码节点我习惯给每个节点命名成能看懂它输出是什么的名字比如代码节点-标准化订单数据、代码节点-按客户分组统计。别就叫Code Node等你有二十个工作流之后光看节点列表就会崩溃。注释要写业务意图不是复述代码。比如// 这里把接口的状态码翻译成内部字段是有效注释// 循环遍历items是废话。团队协作时代码注释的价值在于让下一个接手的人知道为什么这样写而不只是写了什么。建议建一个公共工作流模板库。把高频用到的代码节点存成模板比如Webhook Body 自动拍平、错误统一包装返回、分页拉取接口数据团队新成员可以直接复制。这比每个人从零想实现方式要稳得多。留意执行记录里的耗时。n8n 执行页面会记录每个节点的耗时如果你发现某个代码节点执行了十几秒一定要警惕是不是在循环里同步请求了是不是重复取全量数据了很多时候光是把$input.all()从循环里提出来耗时就大幅下降。还有一个我踩过不少次的小坑在为每个 Item 执行模式下使用$input.all()你不光性能受损还可能因为引用同一个数组导致逻辑混乱。这时候优先用$json或者$input.item把关注点放在当前这条数据上。另外如果你准备把 n8n 用到企业级代码节点的版本控制最好也纳入 git。工作流本身导出为 JSON 文件代码节点的内容都在这份 JSON 里。你完全可以定期把工作流 JSON 备份到仓库代码节点的重要修改留痕出问题的时候回滚才不慌。说到底代码节点就是把你从图形节点的限制里解放出来的那个口子。它让我用 n8n 搭建工作流的时候不再是一个被固定组件框住的拼图工而是一个真正在写代码、控制数据流的开发者。希望这篇文章能帮你少走一些弯路把精力花在真正有价值的业务逻辑上。
