执行成功但数据不对:先怀疑数据形状

工作流跑完了,执行记录上写着成功,绿色勾一路到底。打开结果一看:合计是 null,订单少了一半,或者标着「未付款」的那笔被判成了已付款。

我最早遇到这种情况,第一反应是表达式写错了,来回改了四十分钟。表达式没错,错的是它拿到的数据结构。节点给的东西和你以为的东西,不是一回事。

这篇讲怎么把这类问题在两分钟内定位下来。需要你能看懂执行记录,会写两行 JS。刚装好 n8n 的,四词那篇更合适。

先给一句判断标准:报错是红色的,说明 n8n 知道出事了;数据不对却一路绿灯,说明它按你给的形状跑完了,只是这个形状不是你要的。

这篇不短,按需要跳:

形状只有四个维度

「数据形状」这个词听着虚,拆开就是四个问题:一共几条、字段套了几层、值是什么类型、字段到底叫什么。四个都能用眼睛看出来,都不用猜。

维度 出错时看到什么 先去哪儿看
条数 重复写入、只处理了最后一条、循环少跑了几轮 连线上那个「N 个项目」的标签
层级 字段取到 undefined,键直接从输出里消失 输出面板切 JSON,看缩进
类型 合计变 null、排序乱掉、判断走错分支 输入面板里值的写法:"1,200.00" 带引号就是字符串
字段名 明明有值,表达式就是不认 把键名展开,一个字符一个字符对

条数和类型最容易出事,因为这两个都不报错。层级和字段名一般会给你一个红色,或者至少给个 undefined,还能顺藤摸瓜。

为什么这些都不报错?因为 n8n 传数据的规则只有一条:上一个节点交出一个数组,下一个节点逐条处理,每条的 json 是个普通对象。它不检查这个对象里有没有你要的字段,也不检查金额是数字还是字符串。业务对不对,它不知道。

先把形状打出来

执行记录里点开节点,左边 INPUT,右边 OUTPUT。默认是表格视图,嵌套字段会加粗,表示「这里面还有东西」。真想看清结构就切 JSON,缩进一目了然。

表格视图有个毛病:数字右对齐,字符串左对齐,一眼看上去分不清 1200 和 "1200"。所以我习惯在看不清的时候插一个临时 Code 节点,什么都不改,只把形状打出来:

const all = $input.all();
const first = all[0].json;

return [{
  json: {
    count: all.length,
    types: Object.keys(first).map(k => k + ' => ' + typeof first[k])
  }
}];

跑一次,看输出。count 是条数,types 里能直接读出 amount 是 number 还是 string。查完把这个节点删掉。它不影响结果,但留在生产工作流里,下一个接手的人会骂人。

还有一种更快的看法:看连线。同一条线两端标的项目数不一样,说明中间那个节点改变了条数。这个信息不用点开任何面板。

条数:一次请求,三条数据,下游跑三遍

HTTP Request 请求一个返回数组的接口,节点交出来的不是「一个装着三条的对象」,是三条 item。这件事我第一次遇到时盯着屏幕看了很久。

n8n 画布上 HTTP Request 节点一次请求返回 3 个项目,下游节点只收到 1 个项目
一次请求,接口返回三条,节点交出三个项目。下游节点会对这三条各跑一遍。

后果很实在:写表格写三行,发消息发三条,调接口调三次。有人遇到这个会去查对方的限流日志,怀疑是不是自己重试了;其实是你把数组交给了一个逐条处理的节点。

反过来,想把三条合成一条往下传,很自然会写成这样:

const all = $input.all();

// 本意是把三条合成一组
return [all];
n8n Code 节点输出面板报错 Code doesn't return items properly,因为返回了二维数组
返回 [all] 是二维数组,n8n 认不出来,报 Code doesn't return items properly。

报错原文是 Code doesn't return items properly,下面补一句 Please return an array of objects, one for each item you would like to output.

文档里写着 Code 节点会帮你补 json 键、帮你自动套一层数组,这两条都是真的。但只对「一层」有效。你把三条再包一层数组,得到的是数组的数组,它不会替你去猜哪层是 item。

正确的合并方式是把数据放进某个字段,而不是多套一层壳:

const all = $input.all();

return [{
  json: {
    list: all.map(i => i.json),
    count: all.length
  }
}];

这样出来是 1 条 item,里面的 list 是一个长度 3 的数组。下游拿 $json.list.length 是 3,拿 $json.list[0].n 是第一条。

「一条 item 里包着数组」和「三条 item」,这两种形状在表格视图里长得挺像,在代码里完全是两回事。前者的条数是 1,后者是 3;前者下游只跑一次,后者跑三次。改之前先确认自己是哪种。

层级:值就在那儿,差一层

Webhook 最典型。同样一个 JSON 请求体,Content-Type 写 application/json,$json.body 是对象,$json.body.orderNo 直接取到值。写成 text/plain,body 是一个字符串,$json.body.orderNo 是 undefined,不报错。

我在自己实例上打了两次一样的请求体,只改 Content-Type。一次 bodyType 是 object,一次是 string,keys 那一栏直接把整串原文当字符串打了出来。n8n 的 Webhook 文档里没写这条规则,只说 $json 里是 { body, headers, params, query }。所以这个只能自己验,或者干脆在入口判一下 typeof。

取不存在的键,和取不存在的对象,结果还不一样。前者静默,后者抛错。

数据是 {"order": {"no": 1}},你写 $json.order.id,输出会变成这样:

{ "w": 1 }

原本想输出的 v 整个消失了。不是 null,是没有这个键。undefined 在 JSON 序列化时被丢掉,所以你连「它存在但是空」这个线索都看不到。

换成 $json.nope.no,nope 这一层根本不存在,就抛:

Cannot read properties of undefined (reading 'no') [line 1]

静默的那种更麻烦。看到输出里少了一个字段,先怀疑层级,别怀疑节点坏了。

类型:null 比报错难查

这是我最常遇到的一类。接口给的金额是 "1,200.00",带千分位、带引号。看着像数字,实际是字符串。Number("1,200.00") 是 NaN,NaN 参加加法还是 NaN,NaN 写进 JSON 变成 null。

n8n Code 节点合计结果为 null,输入面板里 amount 是带千分位的字符串
左边输入里 amount 是带引号的 "1,200.00",右边合计出来是红色的 null。执行状态是成功的。

注意几个细节。执行是成功的,没有红色报错。total 是 null,不是 0。代码里 typeof total 仍然是 "number",因为 NaN 在 JS 里就是 number。

所以下游判 if (!total) 会走进「没有金额」的分支,报表里这一列是空白,SUM 会跳过它,平均值会少算一条。查的时候你会先怀疑接口没给数据,而接口明明给了。

null 和 0 在业务上是两件事。0 是「算出来是零」,null 是「算不出来」。数据库里一个允许 null 的金额字段,混进 null 之后,月底对账要花半天。

排序是同一个问题的另一个面。JS 的 sort() 不带比较函数时按字符串比:

['9', '10', '100', '25'].sort()
// ['10', '100', '25', '9']

从 CSV 或者接口来的数字,默认都是字符串。要按大小排,必须自己给比较函数:

rows.sort((a, b) => Number(a.amount) - Number(b.amount));

布尔值更阴。字段里存的是字符串 "false",IF 节点选了布尔「为真」,严格模式下直接报错:

n8n IF 节点报 Wrong type 错误,提示 Convert types where required 开关处于关闭状态
报错原文:Wrong type: 'false' is a string but was expecting a boolean [condition 0, item 0]。面板中间那个 Convert types where required 是关着的。

报错里给了两条建议,一条是打开「Convert types where required」,一条是给字段加 .toBoolean()。大多数人会选第一条,因为改起来最省事。

打开之后确实不报错了。然后这单标着「未付款」的订单,走了已付款分支。

n8n 打开类型转换后,paid 为字符串 false 的订单仍然走了 true 分支
输入里 paid 明明是 "false",true 出口亮了,false 出口是灰的,下游「记为已付」执行了一次。

我试了三个值:'false' 和 '0' 都走 true 出口,只有空字符串走 false。这个开关做的是「非空字符串都算真」,跟你想的「把 false 转成 false」不是一回事。

我的建议是这个开关别乱开。要么在入口把类型转干净,要么用字符串比较(「等于 false」),别指望它替你猜。一个字段转错,后面十个节点全白跑,而且全程绿灯。

字段名:一个空格就够了

字段名带空格,点号写法直接崩:

{{ $json.Order ID }}

报错是 invalid syntax,没有下文,不告诉你是哪个字符的问题。换成中括号就正常:

{{ $json['Order ID'] }}

JS 里点号后面只能跟合法标识符,空格不是。n8n 的表达式求值器不给你兜这个。

大小写也算。OrderID、orderId、orderid 是三个不同的键。从别人的接口拿数据,最好把键名复制过来,别凭印象打。

还有一种看不见的:CSV 带进来的全角空格、BOM 头、末尾多一个换行。键名在屏幕上长得一模一样,粘进表达式就是不匹配,报的也是 undefined。这种我不跟它较劲,直接在入口重命名成驼峰,后面所有节点都省事。

编辑字段默认会丢字段

编辑字段(Edit Fields)节点的语义是「输出只包含我定义的东西」,所以 Include Other Input Fields 默认是关的。

n8n 编辑字段节点未开启 Include Other Input Fields,输出只剩 total 一个字段
左边输入三个字段,右边输出只剩 total。中间那个开关是灰的,表示其他字段全被丢掉。

这个默认值有道理,脱敏、精简、给下游一个干净结构都靠它。但如果你只是想加一个字段,忘了打开开关,下游所有 $json.orderNo 都会变 undefined。而且这个错很难当场发现,通常在三个节点之后才爆出来,那时候你已经忘了自己动过这个开关。

我的做法是:要加字段就打开开关,要脱敏就新建一个节点专做这件事,别在一个节点里同时干两件事。

图钉:改了代码,结果没变

n8n 可以把某个节点的输出固定住,叫 pin data。固定之后这个节点不再执行,下游永远拿固定住的那份数据。画布上那个节点右下角会多一个图钉标记。

n8n 画布上被固定数据的节点带紫色图钉标记,代码改了输出仍是旧值
「造数」节点右下角那个小图钉,就是它。这个节点的代码我改过两次,输出一直是钉住的 99。

我专门试了一遍:节点代码 return [{ json: { n: 1 } }],钉住一份 n: 99 的数据。把代码改成 n: 2,跑完下游拿到的还是 99。清掉固定数据再跑,才是 2。

它本来是给调试用的:不想每次都打外部接口,就把一份数据钉住反复调下游。问题在于钉住之后很容易忘,表现和「代码没生效」一模一样。

看到结果和代码对不上,先看画布上有没有图钉。取消的位置在输出面板顶部那条横幅里,有个 Unpin,不是右键菜单。文档里也写了,钉住的数据只在开发调试时用,生产执行不生效——所以线上跑出来的结果和你在编辑器里看到的不一样,也可能是这个。

改完怎么确认

三个检查,做完两分钟。

  1. 关键节点看条数。输入 3 条,输出也该是 3 条,除非你明确要合并或拆分。数字对不上就是形状问题,别往下查业务逻辑。
  2. 入口节点做类型断言。不符合就让它红,别让它悄悄变 null。
  3. 拿一条已知答案的数据跑一遍,人工对一次结果。之后每次改完都拿同一条。

类型断言可以这样写,放在入口第一个 Code 节点里:

const all = $input.all();

return all.map((item, i) => {
  const raw = String(item.json.amount ?? '').replace(/,/g, '');
  const amount = Number(raw);

  if (!Number.isFinite(amount)) {
    throw new Error('第 ' + (i + 1) + ' 条金额不是数字:' + item.json.amount);
  }

  return { json: { ...item.json, amount } };
});

这段的作用是把「静默变 null」换成「当场报错」。报错里带上是第几条、原值长什么样,比执行记录里翻半天强。抛错之后执行会红,你可能觉得吵,但总比月底对账时发现少了两万块好。

金额这种字段,我宁可它在入口炸一次。

五个报错原文

报错 真正的原因
Code doesn't return items properly 返回值不是「一层对象数组」。常见是返回了二维数组、字符串、单个数字
Cannot read properties of undefined (reading 'no') [line 1] 中间那层对象不存在,比如 $json.nope.no
Wrong type: 'false' is a string but was expecting a boolean [condition 0, item 0] IF 选了布尔比较,字段实际是字符串
invalid syntax 表达式里字段名带空格或非法字符,没加引号
输出里某个字段凭空消失 值算出来是 undefined,序列化时被丢掉了,不是 null

前四条至少给你一句话,第五条什么都不给。所以看到「字段少了」这种描述,先按层级和类型两个方向查。

安全:执行记录存的是整包数据

排查形状最方便的地方就是执行记录,它同时也是泄露面最大的地方。默认配置下,每次执行的输入输出都存一份,任何能登录这个 n8n 的人都能翻到,失败的那次也存。

几条具体的:探针节点别把整条 json 打出来,选几个字段就够,尤其是订单、客户表这种;生产工作流的执行记录按需清理,或者把保存策略调成只存失败;截图发出去之前,看一眼左边输入面板,手机号、地址、密钥经常就在那儿。

我截图的时候把演示数据换成了 A-1 这种编号,不是怕,是没必要把真实单号发出去。

小结

形状不对不报错,是因为 n8n 只负责把数组传下去,不负责判断这个数组对不对。四条线索:条数、层级、类型、字段名。

查的时候从最近一个「结果还正常」的节点开始,往右一个个看输出,第一个不对劲的地方就是它。别从最后一个节点倒推,那样会把上游的问题当成下游的 bug 改。

修的时候在入口修。一个字段的类型错了,你在下游每个节点都得防一遍,防到最后没人记得为什么。

接着往下:数据在节点之间怎么流动讲的是 item 数组本身,四个词那篇讲 workflow 和 execution 的关系。这两篇是地基,本篇是地基上那些裂缝。上一篇是 n8n 触发器全解。

参考资料

最后更新:2026 年 11 月 20 日,用的是 n8n 2.43.7。

THE END