n8n-binary-and-data

n8n 二进制数据和数据

n8n 处理两种数据：JSON（位于 $json 中）和二进制数据（位于 $binary 中），二者并行流动。在 Agent 工具、存储和显示场景（聊天界面、消息渲染）中处理二进制数据时有不少需要注意的地方。

如需了解表格存储（Data Tables），请参阅 n8n-data-tables 技能。

必须遵守

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 工具（连接到 LangChain 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 技能。它是一个独立的功能界面，有自己的注意事项（默认列、无外键、无 JSON 列类型、手动映射界面的特殊行为）。

参考文件

文件	何时阅读
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 引用