做自动化工作流做到一定阶段，你会发现一个规律：凡是涉及二进制文件流的流程，翻车率永远比纯 JSON 流程高一个量级。文件下载下来打不开、邮件附件变成 0KB、多节点上下文传递时二进制数据“神秘消失”——这些坑几乎每个 n8n 玩家都踩过。这篇文章我就围绕 n8n 里的二进制文件流管理和复杂上下文传递，把底层原理、典型场景、可复现的操作步骤和排查思路一次讲清楚。
1. 为什么二进制文件流是 n8n 的“老大难”
1.1 n8n 的底层数据模型：一个以 JSON 为主的世界
n8n 的工作流本质上是在节点之间传递数据项（item）。每个 item 的核心结构是{ json: {...}, binary: {...} }。json字段里可以放任意可序列化的对象，而binary字段是专门留给二进制数据的“特殊通道”。
但在实际使用中，绝大多数文档、教程、示例都围绕json展开，导致很多用户默认“只要在节点输出里能看到数据，就能往下传”。二进制数据就不是这么回事。binary字段里通常包含data（Base64 编码的字符串）、fileName、mimeType、fileSize等元信息。
有个关键点要知道：n8n 内部对二进制数据的处理，并不是每个节点都“无条件原样透传”的。比如Set节点如果被配置成“替换整个输出数据”，它可能会把上游的binary字段一起丢掉；Code节点如果你手动构造了一个新对象返回，却没有显式复制binary，那文件数据也会在这一步断掉。理解这个数据结构，是解决一切二进制流传递问题的前提。
1.2 一张登机牌和托运行李的关系
我经常用“登机牌和托运行李”来类比 n8n 里的 JSON 和二进制数据。json字段是登机牌，轻量、可打印、方便查看；binary字段是托运的行李箱，体积大、不能直接塞进登机牌里。
你拿着登机牌到了登机口，真正上飞机的是行李箱。中间如果换乘（经过多个节点），每段旅程都要重新确认行李有没有被转运过去。最怕的就是某个中转柜台（节点）只处理登机牌，把行李留在原地。这个类比能解释两个现象：
- 为什么不能把文件直接塞进
json字段？因为 Base64 编码会让体积膨胀约 33%，一个 100MB 的文件变成 JSON 字符串直接爆掉执行内存，而且下游节点未必能识别这个字符串是文件。 - 为什么有时候节点输出面板看得到
binary，到了下一步却取不到？因为部分节点在内部转换中只保留了json结果，并没有把binary引用继续传递。
搞懂了这一层，你再去定位“文件到底在哪一步丢的”就有方向了。
2. 先看清场景：哪些上下文传递最容易出问题
2.1 四类典型场景
不是所有二进制流场景难度都一样。我按实际项目经验把它们分成四类：
第一类是“下载-处理-保存”。从外部 API 下载 PDF、图片、Excel，经过简单改名或转换后，保存到本地、对象存储或作为邮件附件发出。这类最简单，只要注意 HTTP Request 节点的输出格式设置即可。
第二类是“API 返回文件流”。第三方接口直接返回文件，或者返回 Base64 编码的字段。前者要用 File Response 模式，后者需要手动把 Base64 字符串转回二进制。
第三类是“多文件汇聚与拆分”。在循环里把每天生成的报表汇总成一个压缩包，或者把一个大文件拆成多段分发到不同分支。这类涉及循环上下文和节点输出合并，最容易丢失尾部数据。
第四类是“跨子工作流传递”。主工作流拿到文件后，调用子工作流处理，或者把文件 ID 传给另一个流程再取回。这类依赖外部存储或临时文件系统，不是单纯的 n8n 节点能解决的问题。
2.2 最容易翻车的几种操作
根据我遇到的 case，最容易出问题的操作基本集中在以下几类：
IF条件分支之后。IF节点本身通常能保留binary，但要警惕分支后面接的节点是否对输入做了“重新包装”。比如你在 True 分支后面加了一个Set节点，把输出 Data 设置为“全部替换”，这时候二进制数据大概率就没了。
Code节点手动构造返回对象。这是大头。很多人写代码时习惯return { json: item.json }，忘了把binary一起带过去。在 Code 节点里，新的返回对象必须同时包含json和binary，否则文件就在这一步消失。
循环处理中只取最后一次结果。Loop或Split Out拆分逐项处理后，如果需要把所有结果再聚合，有些人只保留了最后一个 item，前面的文件自然就丢了。
远程执行器或队列模式下使用本地临时文件。如果你用了 worker 节点或者持久化队列，工作流可能被分配到不同进程执行，基于本地文件系统写入的临时文件路径在后续节点里不可用，导致文件找不到。
3. 实操：构建一个文件不丢的 n8n 工作流
3.1 第一步：从 API 下载二进制文件，响应格式务必设置为 File
很多人在这一步就栽了。用HTTP Request节点请求一个文件接口时，如果直接把响应格式留在默认的 JSON，n8n 会把文件内容当作普通文本或 JSON 字段展示，而不是放进binary槽位。
正确的做法是：在HTTP Request节点配置里，找到“Response Format”，把它从JSON改成File。改成 File 之后，n8n 会自动把响应体写入二进制数据区，并在输出的binary字段里生成一个文件项，通常名为data，包含fileName、mimeType、data（Base64）等属性。
看着很简单，但有三个细节值得注意：
一是少数接口在返回文件的同时还会附带自定义响应头，例如文件名放在Content-Disposition里。如果 n8n 没有自动识别，你可能需要在后面的节点手动设置fileName。
二是有些接口返回的文件其实是个 JSON 字符串，里面某个字段才是 Base64 编码的文件内容。这种情况用 File 模式反而会把整个 JSON 文本当成文件保存。正确解法是先以 JSON 模式接收，再用 Code 节点把 Base64 字段转换并写入binary。
三是响应格式改成 File 后，节点输出面板里通常看不到文件内容的预览，只能看到binary对象。这会让很多新手误以为“没拿到数据”，其实文件已经在你手上了。
3.2 第二步：用 Code 节点读文件、改名、重新打包
拿到二进制之后，最常见的需求是改名、校验、或者根据上下文重新设置元信息。一个典型场景是：下载的文件名是接口返回的一长串 ID，但业务上需要把文件名改成订单号加日期。
在Code节点里，可以用这样一段 JavaScript 来读取和改写文件：
// 上一个节点输出的 item const binaryData = item.binary.data; if (!binaryData) { throw new Error('没有找到 binary.data 字段，请检查上游节点是否启用了 File 响应'); } // 从 Base64 解码成 Buffer 以便校验或转换 const fileBuffer = Buffer.from(binaryData.data, 'base64'); // 这里可以基于上下文动态构造新文件名 const newFileName = `order_20250115_${$json.orderId}.pdf`; // 保留原有 binary 字段并更新文件名 return { json: $json, binary: { data: { ...binaryData, fileName: newFileName, }, }, };需要特别注意的是，如果你在 Code 节点中想创建一个全新的二进制数据，而不是修改现有的，不能直接在返回对象里拼字符串，必须借助 n8n 提供的辅助方法：
const newFileBuffer = Buffer.from('hello n8n', 'utf-8'); const newBinary = await this.helpers.prepareBinaryData( newFileBuffer, 'output.txt', 'text/plain' ); return { json: { ok: true }, binary: { output: newBinary, }, };prepareBinaryData会返回一个符合 n8n 内部格式的二进制对象，包括 Base64 数据和正确的元信息。你可以在这个对象基础上继续覆盖fileName。
另一个常见操作是把二进制数据和上下文拼在一起。比如下游需要知道“这个文件是哪一个流程里生成的”，可以在json字段里额外塞几个标记字段，这样后面的分支节点就能根据json里的信息做条件判断，而不用去解析二进制文件本身。
3.3 第三步：把文件真正“落地”
文件处理完之后，落脚点通常是保存到本地目录、对象存储或作为附件发送。
保存到本地用Read/Write Files from Disk节点，操作路径选择“Write”，指定目标目录和文件名。文件名最好直接从上游binary.data.fileName引用，用表达式写：
{{ $json.binary.data.fileName }}不要自己硬编码一个固定文件名，不然多个 item 并发执行时会互相覆盖。
发送邮件用Email节点，在附件配置里选择“Binary Property”，填上二进制字段名。这里最容易踩的坑是：你以为附件已经加上了，但收件人收到的却是一个乱码文件。乱码通常不是因为 n8n 发送错误，而是上游二进制数据本身就已经被破坏或者被 Base64 转换了两次。
有一种简单的验证方法：在发送前加一个Code节点，把文件头几个字节打印出来。比如一个标准的 PDF 文件头应该是%PDF，图片文件有固定的魔数。如果文件头都不对，说明上游已经坏了，别急着检查邮件节点。
4. 高阶操作：分支、循环、自定义上传中的二进制流处理
4.1 分支之后怎么保留二进制数据
条件分支是二进制流传递的重灾区。IF节点本身一般不会丢文件，但真正的问题出现在分支的后续节点里。
举个例子，一个工作流根据文件扩展名做不同处理：PDF 走转文本流程，图片走压缩流程。如果你在IF后面直接接入处理节点，并且处理节点内部使用“Replace All”之类的设置，二进制数据可能被覆盖。稳妥的做法是，在分支之后，先用一个Code节点做“二进制显式透传”，确认binary字段被保留。
显式透传的代码很简单：
return { json: $json, binary: item.binary, };这段代码不改变任何业务内容，只是把二进制原样带过。别小看这一步，它相当于给行李做了个标记，确保送到下一个节点时行李箱还在。
如果分支前后你对json字段做了大量重组，最安全的策略永远是：先透传，再改json，最后才处理binary。把影响范围拆开，排查时就容易定位。
4.2 在循环中收集多个文件并合并
另一个场景：循环执行多次请求，每次生成一个文件，最后需要把它们合并成一个输出。很多人在聚合阶段发现，循环里的文件“跑到最后一次就没了”。
原因很常见：你在循环内部使用的临时变量被覆盖了，或者每次迭代都只返回当前 item，前面的文件没有被收集进一个数组。
推荐做法是：在循环外维护一个“文件收集器”。具体实现可以用一个Code节点先初始化空数组，在循环内部把每次的binary数据推入数组，循环结束后统一处理。
假设你有一个循环节点，每次输出一个包含二进制数据的 item，聚合节点里可以这样写：
// 聚合节点，接收循环输出的所有 items const collected = []; for (const item of $input.all()) { if (item.binary && item.binary.data) { collected.push({ fileName: item.binary.data.fileName || `file_${collected.length}.bin`, mimeType: item.binary.data.mimeType, data: item.binary.data.data, }); } } // 这里只是把收集结果放到 json 下面，实际使用时再在后续节点转换 return { json: { fileCount: collected.length, files: collected, }, };然后你可以再用一个Code节点把收集到的文件重新包装成多个输出 item，或者调用prepareBinaryData生成合并文件。
需要注意循环体内的Set节点，如果它被配置为“只保留部分字段”，会过滤掉binary，所以循环内部不要随便加Set。
4.3 与外部 API 的 multipart/form-data 上传
除了保存和发送邮件，n8n 还经常需要把文件上传到第三方系统。很多第三方接口要求multipart/form-data格式，这比直接发文件内容要复杂一点。
n8n 的HTTP Request节点在 Body 配置里选择Form-Data，可以添加字段，文件类型选择File，然后指定来源二进制字段名。这是最标准的做法。
但有些时候，第三方接口要求同时传文件和其他业务参数，且文件必须以某个固定字段名出现。此时需要注意：如果使用的是自定义Code节点，不要直接把 Base64 字符串塞进 body 里发送，因为那会被当成普通文本字段。
最可靠的方式是借助 n8n 的辅助函数构造 FormData：
const formData = await this.helpers.getFormData(); formData.append('file', Buffer.from(item.binary.data.data, 'base64'), { filename: item.binary.data.fileName, contentType: item.binary.data.mimeType, }); formData.append('orderId', $json.orderId);然后把formData作为请求体发出。getFormData处理了 multipart 分界线和二进制编码，比自己拼字符串稳定得多。
如果上游已经没有二进制数据，只有一个 Base64 字符串，你可以先转换成 Buffer，再走上面的流程。转换本身没难度，难在很多人不知道prepareBinaryData和getFormData这两个辅助函数的存在。
5. 常见问题排查速查表
5.1 文件“神秘消失”的五个原因及对策
下面整理了我最常遇到的五种情况、原因和检查路径：
| 现象 | 常见原因 | 排查与解法 |
|---|---|---|
| 下游节点里 binary 字段为 undefined | Code 节点构造新 item 时没有复制 binary 字段 | 在最终 return 的对象里显式加上binary: item.binary |
| 下载下来文件打不开，是乱码文本 | HTTP Request 没有设置 Response Format 为 File | 检查节点配置，打开 File 响应模式 |
| 文件内容是一长串 Base64 | 上游是文本字段，你需要手动转换而不是直接保存 | 用 Buffer.from(base64String, ‘base64’)，配合 prepareBinaryData |
| 文件名全部变成 data 或乱码 | 接口返回头没有文件名，或编码不一致 | 在 Code 节点中显式设置 fileName，必要时用 encodeURIComponent |
| 保存目录里看不到文件 | 用了相对路径或目录不存在 | 使用绝对路径，或先创建目标目录，检查执行用户权限 |
5.2 文件损坏、大小不对如何快速定位
文件损坏的问题，我建议从“数据链路”角度排查，而不是猜。
第一步，确认二进制数据源是否正常。在获取文件的节点后面加一个Code节点，打印文件大小和文件头几个字节。
const bin = item.binary.data; const buffer = Buffer.from(bin.data, 'base64'); console.log('文件名:', bin.fileName); console.log('文件大小:', buffer.length); console.log('文件头十六进制:', buffer.subarray(0, 4).toString('hex'));比如 PDF 文件头是25504446，对应 ASCII 是%PDF。JPEG 文件头是FFD8FF。如果文件头不符合预期，说明在下游处理之前文件已经坏了。
第二步，检查文件大小。如果上游文件大小是 5MB，到了发送节点变成了 6.7MB，说明中间发生了一次 Base64 转换但没有还原；如果变成了几百字节，说明中间某个节点只截取了部分内容。
第三步，检查是否经过了不必要的文本操作。比如有人用Code节点给文件拼接了一个前缀，字符串操作直接污染了二进制内容，这种损坏是不可逆的，只能回到上游重做。
5.3 queue 模式与远端 worker 的二进制约制
如果 n8n 跑在队列模式或者分布式 worker 架构下，还有一个容易踩的隐藏坑：本地文件系统不可共享。
举个例子，你用Execute Command节点生成了一个临时文件，路径写死在/tmp/generated.zip。下一个节点如果被调度到另一台 worker 上执行，它就找不到这个文件。同理，Read/Write Files from Disk写入的路径必须确保运行在同一个文件系统上，或者直接改用对象存储。
两条经验供参考：第一，跨节点传递大文件时，优先考虑在binary字段里传数据，而不是依赖临时文件路径；第二，如果二进制文件实在太大，不要硬塞进 n8n 的执行上下文，可以把文件先传到对象存储，然后把 URL 作为普通字符串传给下一个节点，让下游自己下载。
这种“外部化存储”的做法有两个好处：执行上下文的内存占用大幅下降，工作流可重试性也更好。文件只在需要下载的节点里临时进入内存，其他阶段只传递一个字符串。
6. 最后分享几个我自己养成的操作习惯
做了这么久的 n8n 二进制流处理，我总结了几条土办法，不一定写在官方文档里，但实测很管用。
第一，凡是涉及二进制数据的 Code 节点，最终返回值里永远把binary和json分开写清楚。不要图省事直接返回某个中间变量，宁可多写两行，也要保证字段显式。
第二，每经过一个关键节点，就检查一次文件头和文件大小。这套逻辑和“单元测试”类似，不需要每次都很正式，但至少确保文件没坏、没丢、没膨胀。很多诡异问题在早期就能拦下来。
第三，文件名和 MIME 类型别指望 n8n 每次都帮你猜对。特别是从 API 动态下载的文件，最好手动从Content-Disposition响应头或者业务字段里提取真实文件名，用 Code 节点显式赋值。
第四，大文件场景下，不要在一个工作流里做太多次二进制数据的“搬运”。每经过一个节点，内存中就可能多一份引用或副本，几十 MB 的文件经过五六个节点，服务很容易被压垮。合理的做法是尽早把文件落地到外部存储，工作流里只传 URL 或 ID。
第五，也是我吃过亏才总结出来的：n8n的节点版本差异很大，不同版本在处理二进制的方式上有些细微差别。如果你照着某个教程配置发现字段对不上，先看一眼版本说明，不要硬改。比如有些版本里HTTP Request的 File 响应默认行为变了，或者Code节点里不能用prepareBinaryData，都可能导致你之前的经验突然失效。
二进制文件流的传递说到底不是一个不可解的难题，只是它的调试链路比 JSON 更长、更不可见。把数据模型吃透，把每个节点的行为摸清楚，再养成好的检查习惯，你会发现在 n8n 里处理文件其实可以很安稳。
