Sharp 锐化图像流水线

要解决什么问题

在 Node 生态里做批量图像处理，常见路径是串起一串 fs.readFile → 第三方库转换 → fs.writeFile 的胶水代码。这类代码的问题不在于"能不能跑"，而在于三点：

• 流水线不可组合：缩放、叠加、转格式的逻辑散落在各处，同一套参数很难在不同任务间复用，也很难单独测试其中某一步。
• 缺乏统一的中间表示：每一步都要把整张图读进内存再吐出来，大图或批量场景下内存峰值很难控制。
• 格式与元数据处理口径不一致：不同格式的压缩参数、色彩空间、EXIF 保留策略各写各的，产物质量难以对齐。

这个技能要提供的，是一个把 Sharp 的变换能力封装成可组合流水线的入口，让 resize → composite → toFormat 这类流程像函数管道一样声明和串接。

它如何工作

核心是围绕 Sharp 构建一条可组合的处理链，关键能力包括：

• resize()：负责尺寸与宽高比控制，是流水线中最常见的第一步。
• composite()：负责图层叠加，例如在底图上盖水印、拼接多张图。
• toFormat()：负责输出目标格式的编码参数，统一产物的落盘口径。

使用时的关键步骤大致是：

1. 读取源图并构造一个 Sharp 实例作为流水线的起点。
2. 按顺序追加变换节点，每一步都接收上一步的产物，形成链式调用。
3. 在末端调用 toFormat() 等输出方法，触发 libvips 侧的实际运算并落盘。

底层依赖 libvips 绑定，所有变换都在 libvips 的 C 层完成，Node 进程只负责编排参数和传递缓冲区。这也是它被定位为高性能批处理方案的原因——批量任务可以共享同一条流水线定义，只替换输入与输出路径。

适用边界与注意点

• 运行环境有硬性要求：依赖 Node-API v9，仅支持 Node.js ^18.17.0 或 >= 20.3.0，同时兼容 Deno 与 Bun。版本不匹配时模块无法加载，这是最常见的失败原因。
• 它是编排层，不是算法库：流水线里具体能做什么，取决于 Sharp / libvips 暴露的能力范围；技能本身不引入新的图像算法。
• 复杂任务需要自行补足策略：流水线定义好之后，输入校验、失败重试、并发控制、中间产物清理仍需调用方处理。
• 上游文档是权威参考：官方文档位于 https://sharp.pixelplumbing.com/，遇到 API 行为差异时以它为准。