n8n-binary-and-data-official

n8n 二进制数据与数据

n8n 处理两种数据：JSON（位于 $json）和二进制数据（位于 $binary），二者并行流动。二进制数据在 Agent 工具、存储和显示场景（聊天界面、消息渲染）中有一些容易踩坑的地方。

有关表格存储（Data Tables），请参阅 n8n-data-tables-official 技能。

不可妥协的原则

1. 二进制数据位于 $binary，而不是 $json。 不要从 $json 读取文件内容。
2. 二进制数据无法通过 Agent 工具边界传递，无论方向如何。 工具参数只能是 JSON（通过 fromAi()），工具结果也只能是 JSON。请先将二进制数据存入存储，然后通过 JSON 传递键或 URL。Agent 的 passthroughBinaryImages: true 允许大模型查看上传的图片以进行视觉分析，但这并不意味着工具可以接收这些图片。请参阅 references/AGENT_TOOL_BINARY.md。

强烈建议的默认做法

• Merge 节点会在上下文中保留二进制数据。 如果某个辅助计算剥离了二进制数据，请将其合并回来，而不是重新获取。请参阅 references/MERGE_FOR_CONTEXT.md。

二进制基础知识

在 n8n 中，每个项都有两个槽位：

{
    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> 用于读取指定属性。大多数文件处理节点都有一个 binaryPropertyName 参数，用来指定 $binary 中的键。

设置二进制数据

生成文件的节点（如带二进制响应的 HTTP Request、Read Files 等）会自动填充 $binary。要在 Code 节点中生成二进制数据：

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

读取二进制数据

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

大多数工作流无需直接读取二进制数据。只需将其传递给使用它的节点（如电子邮件附件、文件上传等）。

更多信息请参阅 references/BINARY_BASICS.md。

Agent 工具的处理方式

Agent 工具（连接到 AI Agent 节点的子工作流、n8n 原生 Agent，或作为 MCP 工具公开的工作流）有一项限制：参数和结果只能是 JSON，不能是二进制数据。这对两个方向都适用。

传入（用户上传 → 工具使用）： 聊天触发器会提供 files[]。Agent 可以设置 passthroughBinaryImages: true 来进行视觉分析，但 fromAi() 无法将二进制数据传递给工具。因此：

1. 预先存储上传的文件：生成一个键，并将文件上传到私有存储。
2. 将这些键注入 Agent 的系统提示词：“传入的文件：[{originalFileName, fileName}]。调用工具时，必须使用 fileName 字段中的值。”
3. 工具的 fromAi('imageName', '...', 'string') 会接收该键。子工作流会从存储中下载文件。

传出（工具生成 → Agent 返回）： 工具生成了一个文件，但无法返回原始二进制数据。

1. 在内部生成二进制数据。
2. 上传到存储，并获取 URL 或键。
3. 返回 JSON：{ ok: true, file_id: '...', url: '...' }。
4. Agent 在回复中嵌入 URL，或者由另一个工具根据键获取文件。

有关完整模式，包括适用于长时间运行工具的通过 webhook 异步处理方案，请参阅 references/AGENT_TOOL_BINARY.md。

合并以在上下文中保留二进制数据

仅处理 JSON 的操作（Edit Fields、Code、IF）通常会从项中剥离二进制数据。要保留它：

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

Merge 会合并数据流，并保留二进制数据。请参阅 references/MERGE_FOR_CONTEXT.md。

聊天界面的 CDN 要求

如果工作流生成了图片，而用户希望将其嵌入聊天消息（Slack、Discord、Teams、Telegram、嵌入式 webhook 聊天等）：

• 仅有项中的二进制数据还不够。 聊天界面不会读取 $binary；它们会渲染引用图片 URL 的消息（或使用平台专属的文件上传 API）。
• 图片必须存放在可通过 URL 获取的位置。 请先上传到 CDN 或对象存储。
• 用户需要自行配置此存储。 n8n 不会内置此功能。

常见选项包括对象存储（S3、R2、GCS、Azure Blob、Vercel Blob、Supabase Storage）以及网盘类服务（Dropbox、Google Drive、OneDrive、Box）。请询问用户使用哪种服务，而不要默认使用 S3。

请参阅 references/CDN_REQUIREMENT.md。

Data Tables

有关 Data Tables，请参阅 n8n-data-tables-official 技能。这是一个独立场景，有其自身的注意事项（默认列、无外键、无 JSON 列类型、手动映射 UI 的问题）。

参考文件

文件	何时阅读
references/BINARY_BASICS.md	首次处理二进制数据，或读取/写入 $binary 槽位时
references/AGENT_TOOL_BINARY.md	Agent 工具需要用户上传的文件，或会生成文件时（任一方向的边界）
references/MERGE_FOR_CONTEXT.md	二进制数据在 JSON 转换后消失，需要重新附加时
references/CDN_REQUIREMENT.md	在聊天界面或其他需要通过 URL 引用图片的地方展示图片时

反模式

反模式	问题所在	修复方法
尝试从 $json 读取文件内容	二进制数据不在 $json 中	使用 $binary
构建直接返回二进制数据的 Agent 工具	工具输出仅支持 JSON，因此二进制数据无法保留	上传到存储空间，在 JSON 中返回键/URL（参见 AGENT_TOOL_BINARY.md）
尝试通过 fromAi 将聊天中上传的文件传递给工具	fromAi 不会携带二进制数据，因此工具什么也收不到	预先将上传内容存入存储空间，在系统提示词中注入键，并让工具通过键下载
设置 passthroughBinaryImages: true，并以为工具现在就能看到文件	此标志只影响大模型看到的内容，不影响工具收到的内容	工具仍需采用“上传并传递键”的模式
JSON 转换后丢失二进制数据	转换输出项中没有二进制数据	使用 Merge 将 JSON 输出与二进制流合并
将图片存储在 n8n 二进制数据中，并期望聊天界面能够显示	聊天界面需要可通过 URL 访问的图片（或平台原生文件上传），而不是原始的 $binary	上传到 CDN，嵌入 URL，或使用平台的文件 API
在 Code 节点中硬编码二进制 base64	会产生庞大的工作流 JSON，速度慢且容易泄漏	正确通过 $binary 引用二进制数据，或上传到存储空间并通过 URL 引用