n8n-binary-and-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Binary and Data

n8n 二进制与数据

n8n handles two kinds of data: JSON (in

$json

) and binary (in

$binary

), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (e.g., chat hub).

For tabular storage (Data Tables), see the n8n-data-tables
skill.

n8n 处理两种类型的数据：JSON（存储于

$json

）和二进制数据（存储于

$binary

），二者并行流转。在Agent工具、存储和展示场景（如聊天中心）中，二进制数据的处理存在一些需要注意的细节。

关于表格存储（Data Tables），请查看**

n8n-data-tables

**技能。

Non-negotiables

必须遵守的规则

Binary is in
$binary
, not
$json
. Don't read file contents from
```
$json
```
.
Binary cannot cross the agent tool boundary in either direction. Tool parameters are JSON only (via
```
fromAi()
```
), and tool results are JSON only. Pre-stage binary in storage and pass keys/URLs through JSON. The agent's
```
passthroughBinaryImages: true
```
lets the LLM see uploaded images for vision, but it does NOT enable tools to receive them. See
```
references/AGENT_TOOL_BINARY.md
```
.

二进制数据存储于
$binary
，而非
$json
。不要从
```
$json
```
中读取文件内容。
二进制数据无法双向跨越Agent工具边界。 工具参数仅支持JSON格式（通过
```
fromAi()
```
传递），工具结果也仅为JSON格式。需预先将二进制数据存储到存储服务中，通过JSON传递密钥/URL。Agent的
```
passthroughBinaryImages: true
```
配置可让LLM“查看”上传的图片以实现视觉功能，但这并不意味着工具可以接收二进制数据。详情请查看
```
references/AGENT_TOOL_BINARY.md
```
。

Strong defaults

Binary basics

二进制数据基础

In n8n, each item has two slots:

{
    json: { ... },           // your data
    binary: {                // your files
        data: {              // 'data' is the typical key; can be any name
            data: '<base64>',
            mimeType: 'application/pdf',
            fileName: 'invoice.pdf',
            fileExtension: 'pdf',
        },
    },
}

$binary.<key>

reads the named property. Most file-handling nodes have a

binaryPropertyName

parameter, the key inside

$binary

在n8n中，每个条目包含两个槽位：

{
    json: { ... },           // 你的数据
    binary: {                // 你的文件
        data: {              // 'data'是常用键名；可自定义名称
            data: '<base64>',
            mimeType: 'application/pdf',
            fileName: 'invoice.pdf',
            fileExtension: 'pdf',
        },
    },
}

$binary.<key>

用于读取指定属性。大多数文件处理节点都有

binaryPropertyName

参数，即

$binary

内的键名。

Setting binary

设置二进制数据

File-producing nodes (HTTP Request with binary response, Read Files, etc.) populate

$binary

automatically. To produce binary in a Code node:

return [{
    json: { ... },
    binary: {
        data: {
            data: Buffer.from(content).toString('base64'),
            mimeType: 'text/plain',
            fileName: 'output.txt',
        },
    },
}]

生成文件的节点（返回二进制响应的HTTP Request节点、Read Files节点等）会自动填充

$binary

。要在Code节点中生成二进制数据：

return [{
    json: { ... },
    binary: {
        data: {
            data: Buffer.from(content).toString('base64'),
            mimeType: 'text/plain',
            fileName: 'output.txt',
        },
    },
}]

Reading binary

读取二进制数据

// In a Code node
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data')
const text = buffer.toString('utf-8')

Most workflows don't need to read binary directly. Pass it through to consumer nodes (email attachments, file uploads, etc.).

See

references/BINARY_BASICS.md

for more.

// 在Code节点中
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data')
const text = buffer.toString('utf-8')

大多数工作流无需直接读取二进制数据，只需将其传递给消费节点（如邮件附件、文件上传等）即可。

更多内容请查看

references/BINARY_BASICS.md

。

Agent tool gymnastics

Agent工具处理技巧

Agent tools (sub-workflows wired into a LangChain Agent, or workflows exposed as MCP tools) have a constraint: parameters and results are JSON, not binary. Affects both directions.

Inbound (user uploads → tool consumes): the chat trigger gives

files[]

. The agent can have

passthroughBinaryImages: true

for vision, but

fromAi()

can't pass binary to a tool. So:

Pre-stage uploaded files: hash a key, upload to private storage.
Inject the keys into the agent's system prompt: "Files passed in: [{originalFileName, fileName}]. Use EXACTLY the
```
fileName
```
field when calling tools."
The tool's
```
fromAi('imageName', '...', 'string')
```
receives the key. The sub-workflow downloads from storage.

Outbound (tool produces → agent returns): a tool generates a file. It can't return raw binary.

Generate binary internally.
Upload to storage, get back URL/key.

Return JSON:

{ ok: true, file_id: '...', url: '...' }

The agent embeds the URL in its response, or another tool fetches by key.

For the full pattern including the async-via-webhook variant for long-running tools, see

references/AGENT_TOOL_BINARY.md

Agent工具（连接到LangChain Agent的子工作流，或作为MCP工具暴露的工作流）存在一个限制：参数和结果仅支持JSON格式，不支持二进制数据。这会影响数据的双向传递。

入站（用户上传 → 工具消费）： 聊天触发器会提供

files[]

。Agent可配置

passthroughBinaryImages: true

以支持视觉功能，但

fromAi()

无法将二进制数据传递给工具。因此：

预存储上传的文件：生成哈希密钥，上传到私有存储服务。
将密钥注入Agent的系统提示：“已传入文件：[{originalFileName, fileName}]。调用工具时请严格使用
```
fileName
```
字段。”
工具的
```
fromAi('imageName', '...', 'string')
```
会接收密钥，子工作流从存储服务中下载文件。

出站（工具生成 → Agent返回）： 工具生成文件后，无法直接返回原始二进制数据。

在内部生成二进制数据。
上传到存储服务，获取URL/密钥。

返回JSON格式结果：

{ ok: true, file_id: '...', url: '...' }

。

Agent将URL嵌入响应中，或由其他工具通过密钥获取文件。

如需包含异步Webhook变体的完整模式（适用于长时间运行的工具），请查看

references/AGENT_TOOL_BINARY.md

。

Merge for keeping binary in context

通过合并节点保留上下文里的二进制数据

A JSON-only operation (Edit Fields, Code, IF) often strips binary from the item. To keep it:

[Source with binary] ─┬─→ [Edit Fields: transform JSON] ─┐
                      │                                    ├─→ [Merge: by position] ─→ [Email with attachment]
                      └─────────────────────────────────────┘

Merge combines the streams, and binary survives. See

references/MERGE_FOR_CONTEXT.md

仅处理JSON的操作（如Edit Fields、Code、IF节点）通常会移除条目中的二进制数据。要保留二进制数据：

[包含二进制数据的源节点] ─┬─→ [Edit Fields：转换JSON] ─┐
                      │                                    ├─→ [Merge：按位置合并] ─→ [带附件的邮件节点]
                      └─────────────────────────────────────┘

合并节点会合并两个流，二进制数据得以保留。详情请查看

references/MERGE_FOR_CONTEXT.md

。

CDN requirement for chat hub

聊天中心的CDN要求

When a workflow generates an image and the user wants it in the chat UI:

Binary on the item isn't enough. Chat hub doesn't read
```
$binary
```
.
The image must be uploaded to a CDN referenced by URL.
The user configures this CDN. Not built into n8n.

Common options span object storage (S3, R2, GCS, Azure Blob, Vercel Blob, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box). Ask the user what they use rather than defaulting to S3.

See

references/CDN_REQUIREMENT.md

当工作流生成图片并需要在聊天UI中展示时：

仅在条目中存储二进制数据是不够的。 聊天中心不会读取
```
$binary
```
中的数据。
图片必须上传到CDN，并通过URL引用。
CDN由用户配置。 n8n未内置该功能。

常见选项包括对象存储（S3、R2、GCS、Azure Blob、Vercel Blob、Supabase Storage）和网盘类服务（Dropbox、Google Drive、OneDrive、Box）。应询问用户使用的服务，而非默认选择S3。

详情请查看

references/CDN_REQUIREMENT.md

。

Data Tables

数据表

For Data Tables, see the n8n-data-tables
skill. Distinct surface with its own gotchas (default columns, no foreign keys, no JSON column type, manual-mapping UI quirk).

关于数据表，请查看**

n8n-data-tables

**技能。这是一个独立的模块，有其自身的注意事项（默认列、无外键、无JSON列类型、手动映射UI的特殊情况）。

Reference files

参考文件

File	Read when
`references/BINARY_BASICS.md`	First time handling binary, or reading/writing the `$binary` slot
`references/AGENT_TOOL_BINARY.md`	Agent tool needs a user-uploaded file, or produces a file (the boundary in either direction)
`references/MERGE_FOR_CONTEXT.md`	Binary disappears after a JSON transform and needs to re-attach
`references/CDN_REQUIREMENT.md`	Showing images in chat hub or other places that need URL-referenced images

文件	阅读场景
`references/BINARY_BASICS.md`	首次处理二进制数据，或读写 `$binary` 槽位时
`references/AGENT_TOOL_BINARY.md`	Agent工具需要处理用户上传的文件，或生成文件时（双向边界场景）
`references/MERGE_FOR_CONTEXT.md`	JSON转换后二进制数据丢失，需要重新附加时
`references/CDN_REQUIREMENT.md`	在聊天中心或其他需要URL引用图片的场景中展示图片时

Anti-patterns

反模式

Anti-pattern	What goes wrong	Fix
Trying to read file content from `$json`	Binary isn't in `$json`	Use `$binary`
Building an agent tool that returns binary directly	Tool output is JSON-only, so binary doesn't survive	Upload to storage, return key/URL in JSON (see `AGENT_TOOL_BINARY.md` )
Trying to pass uploaded chat files into a tool via `fromAi`	`fromAi` doesn't carry binary, so the tool gets nothing	Pre-stage uploads to storage, inject keys in the system prompt, and have the tool download by key
Setting `passthroughBinaryImages: true` and assuming tools can now see the file	The flag only affects what the LLM sees, not what tools receive	Still need the upload-and-pass-key pattern for tools
Losing binary after a JSON transform	The transform's output item doesn't have binary	Use Merge to combine the JSON output with the binary stream
Storing image in n8n binary and expecting chat hub to display	Chat hub needs URL-accessible images, not raw binary	Upload to CDN, embed URL in response
Hardcoding binary base64 in a Code node	Massive workflow JSON, slow, leaky	Reference binary via `$binary` properly, or upload to storage and reference by URL

反模式	问题所在	修复方案
尝试从 `$json` 中读取文件内容	二进制数据不在 `$json` 中	使用 `$binary`
构建直接返回二进制数据的Agent工具	工具输出仅支持JSON格式，二进制数据无法保留	上传到存储服务，在JSON中返回密钥/URL（查看 `AGENT_TOOL_BINARY.md` ）
尝试通过 `fromAi` 将聊天中上传的文件传递给工具	`fromAi` 不携带二进制数据，工具无法获取内容	预先将上传文件存储到存储服务，在系统提示中注入密钥，让工具通过密钥下载
设置 `passthroughBinaryImages: true` 并认为工具现在可以访问文件	该配置仅影响LLM能看到的内容，不影响工具接收的数据	仍需使用“上传并传递密钥”的模式来让工具处理文件
JSON转换后丢失二进制数据	转换后的输出条目不包含二进制数据	使用Merge节点将JSON输出与二进制数据流合并
将图片存储在n8n的二进制数据中并期望聊天中心展示	聊天中心需要可通过URL访问的图片，而非原始二进制数据	上传到CDN，在响应中嵌入URL
在Code节点中硬编码二进制数据的base64	工作流JSON体积过大、运行缓慢、易泄露	正确通过 `$binary` 引用二进制数据，或上传到存储服务并通过URL引用