n8n-nodes-ai-image-optimizer

在自托管 n8n 中本地压缩、缩放并转换图片格式。

重要说明

• 仅支持自托管 n8n 2.x；这是一个需要 sharp 运行时依赖的社区节点，不宣称支持 n8n Cloud。
• 图片在 n8n 进程本地处理，不会上传到第三方压缩 API，也不需要凭据、AI 模型或 AI Tool 连接。
• 节点显示名为“图片压缩”。内部节点名 aiImageOptimizer、npm 包名、操作值和输出契约保持不变。
• 新节点使用 v2 配置（version: [1, 2]、defaultVersion: 2）；旧工作流仍可读取 preset 和 legacy options。
• AI Agent 工具不能直接接收 Binary；将本节点放在 Agent 前，并在 Agent 中启用 Binary 图片传递。

安装

在 n8n 中打开 设置 → 社区节点 → 安装，输入 n8n-nodes-ai-image-optimizer。安装后重启 n8n，使社区节点在编辑器中可见。

发布验证使用真实 npm tarball 安装到 n8n 用户目录的 .n8n/nodes。n8n-node dev 使用不同的 custom-directory 开发布局，不能替代发布包安装验证。

快速使用

工作流：图片来源 → 图片压缩 → AI 节点。

默认值如下：

• 图片来源：二进制文件（Binary）
• 快捷模式：AI 视觉
• 输入字段和输出字段：data

Binary 模式从当前 item 的 $binary.data 读取图片；如需使用别的字段，在表单中改写输入 Binary 字段。输出仍写回 $binary.data，并在 $json.imageOptimization 写入统计信息。

常用参数和表达式示例：

| 参数 | 默认值 | 示例 | | --- | --- | --- | | 图片来源 | 二进制文件（Binary） | URL 流程选择“图片 URL” | | 快捷模式 | AI 视觉 | 选择 OCR、参考图片或自定义 | | 输入/输出 Binary 字段 | data | 读取 {{$binary.data}}，结果仍在 {{$binary.data}} | | 图片 URL | 空 | 可填写 {{$json.url}} 等 n8n 表达式 | | 输出文件名 | 自动 | 可填写 {{$json.name}} 等表达式 |

表达式只应引用当前 item 的非敏感字段；不要把凭据、Authorization 或私有 URL 写进工作流 JSON、查询字符串或日志。

四种快捷模式

v2 的四个操作值是固定的 aiVision、ocr、referenceImage、custom，对应编辑器中的以下操作：

| 操作 | 尺寸上限 | 编码与参数 | 说明 | | --- | --- | --- | --- | | AI 视觉 (aiVision) | 1600×1600 | JPEG/WebP，质量 84 | 不放大图片，移除元数据 | | OCR (ocr) | 2400×2400 | 无损 WebP | 移除元数据 | | 参考图片 (referenceImage) | 2048×2048 | Auto 质量 88 的 JPEG/WebP | 移除元数据 | | 自定义 (custom) | maxWidth × maxHeight，不超过 100 MP | 格式、质量、无损等由表单指定 | 可选是否放大 |

前三个固定快捷模式始终移除元数据。preferSmallerEquivalentOutput 默认开启：如果重新编码后的文件没有更小，节点可以保留原始 Binary，并在统计中将 usedOriginal 标记为 true。

使用图片 URL

将图片来源切换为 图片 URL 后填写公共 https:// URL。URL 字段只在该来源下显示；默认超时 15,000 ms、最多跟随 3 次重定向，且最大输入为 25 MiB、100 MP。

需要身份验证的 URL 不应直接交给此节点。先使用 HTTP Request 节点和 n8n Credential 下载为 Binary，再切回二进制文件（Binary）模式处理。

自定义压缩

选择 自定义 后，表单会显示核心字段：最大宽度、最大高度、输出格式、质量和无损；“放大图片”默认关闭。高级选项默认折叠，可按需设置输入/输出字段、输出文件名、保留更小等价输出和元数据策略。

自定义尺寸受 100 MP（maxWidth × maxHeight）上限约束。质量适用于有损格式；无损选项只对支持它的格式生效。

输出

节点为每个输入 item 保留原有 JSON、其它 Binary 字段、item 数量和 paired-item lineage，并将结果写入默认 $binary.data（或指定的输出 Binary 字段）。

同时写入 $json.imageOptimization，其中包含来源、所选 preset、原始/输出字节数、输出尺寸与格式，以及是否使用原始文件（usedOriginal）。JSON 中不会写入图片 Base64。

安全

• 仅允许公共 HTTPS URL；字面私有/保留 IP、非 HTTPS Fake-IP、未知或特殊用途域名，以及解析到其它私有地址的请求默认拒绝。
• Clash、Mihomo 等透明代理将公共域名解析到 198.18.0.0/15 Fake-IP 时可正常工作；这不放宽真实私有网络边界。
• 重定向会逐跳重新执行同样的协议、域名和地址检查；TLS 校验保持开启。
• 允许私有网络 URL 仅适用于固定且可信的局域网资源。不要对 Webhook、表单或其它不可信输入开启，否则可能暴露内部服务。
• 节点在本地执行，不向外部服务发送图片；运行时仍受 25 MiB、100 MP、格式和动画/多页限制。

支持的输入格式

支持静态 JPEG、PNG、WebP、AVIF 和单页 TIFF。SVG、PDF、视频、动图和多页 TIFF 会被拒绝。输入必须是有效图片 Binary，或能返回图片内容类型的公共 URL。

兼容旧工作流

导入的 v1 工作流继续使用 preset 和 legacy options，无需手动迁移；节点会按原有 preset/options 解释这些参数。新建节点默认使用 v2 的 operation 和新的字段层级，显示名、操作标签和错误信息会使用中文。

程序化引用仍保持：节点类型 aiImageOptimizer、npm 包 n8n-nodes-ai-image-optimizer、操作值 aiVision | ocr | referenceImage | custom、默认 Binary 字段 data，以及 $json.imageOptimization 键。

本 README 不伪造 n8n 编辑器截图。发布包包含同构的浅色/深色主题 SVG 节点图标（imageOptimizer.svg 与 imageOptimizer.dark.svg），不包含旧 PNG。实际 UI 与安装结果以对应版本的真实 tarball 烟测记录为准。