用途:在 n8n 工作流中正确处理文件与二进制数据。每个 n8n item 有两个独立槽位:$json 存结构化数据,$binary 存文件字节,二者并行流转。文件内容(PDF、图片、zip)只存在于 $binary,$json 最多存元数据。
主要能力与规则:一、文件内容在 $binary.<key>,不在 $json;HTTP 下载、Read Files、邮件附件触发后字节都在 $binary。二、二进制无法跨越 AI 智能体工具边界(双向),工具参数与返回值只能是 JSON,需先把文件暂存到存储,再通过 JSON 传 key 或 URL。三、聊天界面(Slack、Discord、Teams、Telegram、Webhook 聊天)按 URL 渲染图片,不读 $binary。
使用方式:HTTP Request 需设 responseFormat: "file",否则字节会变成乱码文本进入 $json。Code 节点读取用 this.helpers.getBinaryDataBuffer(0, 'data'),写入需自行构造 data(base64)、mimeType、fileName、fileExtension。Code 节点返回 [{ json: {...} }] 而不重新附加 binary 会静默丢文件,需返回 binary: $input.item.binary。JSON 转换节点(Edit Fields、IF 等)可能剥离 $binary,可用 includeOtherFields 透传,或分流后用 Merge 的 combineByPosition 按位置合并。
限制:$fromAI() 不能携带二进制;工具参数与返回仅 JSON;n8n 无内置 CDN 或公共文件托管,需用户自备存储(S3、R2、GCS、Dropbox、Google Drive 等),敏感内容建议用带过期时间的签名 URL;passthroughBinaryImages 仅影响 LLM 视觉输入且仅限图片,不能让工具收到文件;getBinaryDataBuffer 仅在 Code 节点可用,Custom Code Tool 沙箱不可用。二进制槽被剥离属静默失败,validate_workflow 不会报错,需通过 n8n_executions 检查执行输出确认。Data Tables 由 n8n-mcp-tools-expert 负责,本技能不涉及。