当 n8n 工作流读取、转换、存储、上传、下载或传输文件和二进制字段，包括多模态代理输入和聊天附件时，使用此技能。

将上传的文件和生成的 URL 视为可能敏感的。在将数据发送到新的外部主机之前获得批准，使用最小的保留和访问范围，避免记录字节或 base64 数据，并且不要在 URL 或工作流字段中嵌入凭据。

每个 n8n 项目都有两个独立的槽：用于结构化数据的 $json 和用于文件字节的 $binary。它们在工作流中并行传输。文件内容——实际的 PDF、图片或压缩包——存放在 $binary 中，而永远不会存放在 $json 中。如果分配错误，你会读取到空字段、中途丢失文件，或者给 AI 代理提供一个它无法使用的工具输入。

这一技能涵盖了二进制存储的位置、如何读取和写入二进制、如何防止二进制被静默剥离、二进制与 AI 代理工具边界之间的硬性隔阂，以及为什么聊天界面需要 URL 而不是原始字节。

binary 内的键（这里是 invoice）是 二进制属性名。大多数文件处理节点都有一个 binaryPropertyName 参数指向它——生产者命名槽位，消费者通过该名称引用它。大多数节点的默认键是 data，所以当没有其他说明时，假设 $binary.data。

$json 和 $binary 是独立的命名空间。像 {{ $binary.invoice.fileName }} 这样的表达式读取文件的元数据；{{ $json.customerId }} 读取数据。它们从不混合使用。

这种分裂也解释了 webhook 的一个陷阱：接收 multipart/form-data 的 Webhook 触发器会将上传的文件放在 $binary 中，而随附的表单字段则放在 $json.body 中——所以上传的文件根本不在 $json 下的任何位置。（webhook 的 $json.body 嵌套属于 n8n-expression-syntax 范畴。）

请参阅 references/BINARY_BASICS.md 了解完整的插槽结构、MIME 类型和大小限制。

你很少手动创建 $binary 插槽——节点会为你自动填充它：

HTTP Request with responseFormat: "file" Response body lands in $binary.data (or the name you set)

Read/Write Files from Disk File contents read into $binary

Storage downloads (S3, Google Drive, Dropbox, etc.) Downloaded file in $binary.

Email triggers with attachments Each attachment arrives in $binary

Provider AI media nodes (image/audio gen) Set options.binaryPropertyOutput so the bytes land where the next node looks

对于 HTTP 下载，唯一重要的字段是 responseFormat。可以通过 nodes-base.httpRequest 上的 get_node 进行确认——将其保持为默认的 JSON/字符串格式通常是下载的文件最终在 $json 中显示为乱码而不是在 $binary 中显示为干净字节的经典原因。

在代码节点中读取和写入二进制

大多数工作流程根本不需要打开字节——它们只是将二进制数据传递给消费者（电子邮件附件、文件上传、Slack 文件）。当你确实需要原始字节时，请在代码节点中操作。

使用 getBinaryDataBuffer 读取 — 不要尝试手动对 $binary..data 进行 base64 解码：

// Code node, "Run Once for Each Item"
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); // (itemIndex, propertyName)
const text = buffer.toString('utf-8');
const length = buffer.length;

return [{
  json: { ...$json, length },
  binary: $input.item.binary,   // pass the binary through, or it's gone
}];

通过自己构建插槽来编写 — 对字节进行 base64 编码，并加上 MIME 类型和文件名：

const text = 'Hello, world!';
return [{
  json: { ok: true },
  binary: {
    report: {
      data: Buffer.from(text).toString('base64'),
      mimeType: 'text/plain',
      fileName: 'report.txt',
      fileExtension: 'txt',
    },
  },
}];

Code 节点的沙箱、辅助工具和执行模式属于 n8n-code-javascript（以及 n8n-code-python）的领域——在语言级别的细节上使用它们。这里需要记住的唯一与二进制相关的事项：返回 [{ json: {...} }] 而不重新附加 binary 的 Code 节点会静默丢弃文件。请参见 references/BINARY_BASICS.md。

仅 JSON 的节点——编辑字段（集合）、代码、IF 等——可以从它们的输出中丢弃 $binary 插槽。工作流验证清理并运行没有错误；只是当邮件节点要附加它时，下游没有该文件。

[Source with binary] ─┬─→ [Edit Fields: change JSON] ─┐
                      │      (binary stripped here)     ├─→ [Merge: combineByPosition] ─→ [Email: attach]
                      └──────────────────────────────────┘
                          (bypass — binary passes through untouched)

combineByPosition 将每个输入的第 N 个项目配对，因此字段数量必须对齐。多条条带点链（upload-early，子工作流）的连接布线和可选方案在 references/MERGE_FOR_CONTEXT.md 中。

这是最锋利的边缘。一个 AI 代理通过 JSON 与其工具（自定义代码工具、调用 n8n 工作流工具、HTTP 请求工具、MCP 工具）进行通信。二进制数据无法通过该管道双向传输。解决方法在两边都是相同的：先将字节存储起来，通过 JSON 传递一个键/URL，然后在另一端获取。

入站 — 用户上传代理工具必须处理的文件：

Outbound——一个工具生成代理必须返回的文件：

在代理上设置 passthroughBinaryImages: true 仅会改变 LLM 对视觉的感知 —— 它 不会 让工具接收文件，而且仅限于图像（不支持 PDF、音频或视频）。对于任何工具，你仍然需要使用上传并传递密钥的模式。完整的模式、哈希策略、存储选择以及长期运行工具的变体都在 references/AGENT_TOOL_BINARY.md 中。

当工作流程生成一张图片且用户希望它显示在聊天消息中时：

询问他们已经使用哪种存储，而不是默认使用 S3——对象存储（S3、R2、GCS、Azure Blob、Backblaze B2、Supabase Storage）和驱动器式服务（Dropbox、Google Drive、OneDrive、Box）都可以使用，并且都会改变 URL 结构。如果他们没有任何存储，Cloudflare R2 是摩擦最小的起点。对于敏感内容，使用带有过期时间的签名 URL，而不是永久公开的 URL。请参阅 references/CDN_REQUIREMENT.md。

对于持久化的表格存储——引用计数的分阶段文件，跟踪哪些键是活跃的，去重——这是 n8n_manage_datatable 的范畴，由 n8n-mcp-tools-expert 拥有。此技能不涵盖数据表。

Reading file contents from $json Bytes live in $binary; $json is empty or metadata only Read $binary., or getBinaryDataBuffer in a Code node

HTTP download without responseFormat: "file" Bytes arrive as mangled text in $json, not clean binary Set responseFormat: "file" on the HTTP Request node

Code node returns [{json:{...}}], no binary The file is silently dropped downstream Re-attach binary: $input.item.binary in the return

JSON transform (Edit Fields/IF) eats the binary Email/upload node finds nothing to attach Pass-through option, or fan out + Merge by position

Passing an uploaded file into a tool via $fromAI $fromAI can't carry binary; the tool gets nothing Pre-stage to storage, inject the key in the system prompt, tool fetches by key

Assuming passthroughBinaryImages lets tools see the file It only affects what the LLM sees, and only for images Still need the upload-and-pass-key pattern for tools

Tool returns raw binary to the agent Tool output is JSON; bytes don't survive (and bloat context) Upload, return { key, url } in JSON

Posting $binary to a chat surface and expecting an image Chat clients render by URL, not raw bytes Upload to storage/CDN, embed the URL or use the platform file API

Hardcoding base64 in a Code node Huge workflow JSON, slow, leaky Reference via $binary, or upload and reference by URL

references/BINARY_BASICS.md First time handling binary, or reading/writing the $binary slot, mime types, size limits

references/AGENT_TOOL_BINARY.md An agent tool needs an uploaded file, or produces one — the boundary in either direction

references/MERGE_FOR_CONTEXT.md Binary disappears after a JSON transform and you need to re-attach it

references/CDN_REQUIREMENT.md Showing images in a chat surface or anywhere that needs URL-referenced images

n8n-code-javascript / n8n-code-python：Code 节点是你读取/写入原始字节的地方（getBinaryDataBuffer，Buffer.from(...).toString('base64')）。这些技能掌控沙箱、辅助工具和执行模式的细节 —— 这个技能掌握规则，即二进制必须在返回时重新附加。

n8n-code-tool：自定义代码工具的沙箱更受限制——没有 $binary，没有 getBinaryDataBuffer，没有 $fromAI。当一个工具需要文件时，它就是通过这个技能的存储键模式来获取文件的。

n8n-工作流模式：代理-工具二进制边界位于带工具的 AI 代理模式内；CDN 流程是生成 → 上传 → 回复 链。

n8n-节点配置：responseFormat、binaryPropertyName、includeOtherFields、binaryPropertyOutput 都是条件字段——使用 get_node 确认用户版本中的确切名称。

n8n-expression-syntax：处理 $binary..fileName 与 $json.body（特别是 webhook 上传）属于表达式领域。

n8n-validation-expert：丢失的二进制插槽是一个静默失败——validate_workflow 不会标记它。通过检查执行来确认其存在。

n8n-mcp-tools-expert：拥有 n8n_manage_datatable（数据表）和 n8n_executions —— 使用后者来确认给定节点中的 binary 插槽是否实际存在。

n8n 错误处理：存储上传和下载失败；入站/出站暂存步骤需要错误分支，以防缺少键时静默出现 404 错误。

使用-n8n-mcp-技能：这些技能如何相互结合的索引。

验证无法捕捉被剥离的二进制插槽——这是无声的失败。请确认它已正确运行：

N8n Binary And Data 实用指南

Handle n8n files and binary data across uploads, downloads, transforms, multimodal inputs, agent tools, and chat surfaces.

开发工具

后端

人工智能

掌握n8n二进制数据处理核心规则：文件内容存于$binary而非$json；二进制无法跨越AI代理工具边界，需先存储并通过JSON传递密钥或URL；聊天界面通过URL渲染图片而非原始字节。学习在代码节点中读写二进制、防止转换过程中文件被静默剥离，以及HTTP下载需设置responseFormat为file的关键操作。

结构化数据

对象存储

文件处理

敏感数据

JavaScript

路由

Agent

JSON

对象存储COS新用户低至1元！


CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

N8n Binary And Data 实用指南

N8n Binary And Data 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐