用 Node.js + sharp 搭一个图片处理服务：缩略图、水印、格式转换、裁剪、压缩全流程

做后端多多少少都会碰到图片用户上传的头像要生成缩略图商品图要打水印前端要 WebP/AVIF 省流量运营丢过来一张 4000×3000 的原图要你压到 200KB 以内。这些活儿如果每次都手动开 Photoshop 显然不现实得有个能跑在服务端、能批量、能接进接口的方案。Node 生态里做这件事最顺手的就是 sharp。这篇把我在项目里用 sharp 搭图片处理服务的完整链路写清楚从 resize 到缩略图裁剪模式、水印合成、格式转换、EXIF 方向修正再到怎么封成 Express 接口最后重点聊聊工程边界——libvips 的内存、并发、大图和「要不要放主进程」这些坑是决定这套东西能不能扛住线上流量的关键。为什么是 sharp而不是 ImageMagick/gmsharp 底层是 libvips不是 ImageMagick。这个差别很实在快。libvips 用的是流式demand-driven处理一边读一边算一边写不需要把整张图完整解码到内存再操作。同样一张大图sharp 通常比基于 ImageMagick 的gm/imagemagick库快 4~8 倍。省内存。因为流式处理 只在需要的区域求值处理一张几千万像素的图常驻内存往往只有 ImageMagick 的几分之一。接口现代。全 Promise/async链式调用TypeScript 类型齐全不用自己拼命令行字符串也没有 shell 注入风险。预编译。npm 装的时候会带对应平台的预编译 libvips 二进制绝大多数情况不用你在机器上单独装 libvips。代价是sharp 的能力集比 ImageMagick 窄它专注「几何变换 格式编解码 合成」不做复杂滤镜、文字排版、GIF 逐帧动画那一套。但对 99% 的服务端图片处理需求sharp 够且更好。安装与第一个 resizenpminstallsharp最基础的用法把一张图等比缩到宽 800constsharprequire(sharp);asyncfunctionresizeDemo(){awaitsharp(input.jpg)// 只给 widthheight 传 null/不传 等比缩放高度自动算.resize({width:800}).toFile(output.jpg);}resizeDemo().catch(console.error);sharp 的输入可以是文件路径也可以是 Buffer比如从 multer 拿到的上传流输出可以.toFile()落盘也可以.toBuffer()拿到内存里直接返回给前端。服务端场景基本都是 Buffer 进、Buffer 出constsharprequire(sharp);// inputBuffer 来自上传/下载outputBuffer 直接塞进 HTTP 响应asyncfunctionprocessBuffer(inputBuffer){constoutputBufferawaitsharp(inputBuffer).resize({width:800}).jpeg({quality:80}).toBuffer();returnoutputBuffer;}一个容易忽略的点sharp 实例是一次性的 pipeline。同一个sharp(input)对象调用两次.toBuffer()行为并不可靠正确做法是每次处理都sharp(input)新建一个 pipeline。如果输入是同一个 Buffer这没什么开销Buffer 是复用的。缩略图与 fit裁剪模式才是重点resize真正的坑在「目标尺寸和原图比例不一致」时怎么办。sharp 用fit参数控制一共 5 种务必搞清楚constsharprequire(sharp);asyncfunctionthumbnails(input){// cover填满 200x200超出部分裁掉最常用的头像/封面缩略图awaitsharp(input).resize(200,200,{fit:cover,position:centre}).toFile(cover.jpg);// contain完整装进 200x200空白处补背景色不裁剪会留边awaitsharp(input).resize(200,200,{fit:contain,background:{r:255,g:255,b:255,alpha:1},}).toFile(contain.jpg);// inside等比缩到「不超过」200x200最终尺寸可能小于目标列表缩略图常用awaitsharp(input).resize(200,200,{fit:inside,withoutEnlargement:true}).toFile(inside.jpg);}几条实战经验头像、商品封面这类要求固定尺寸的用fit: cover配合position控制裁剪锚点centre、top、attention等。position: attention会让 libvips 用熵/肤色启发式找「最值得保留」的区域再裁做人物缩略图比死心眼裁中间强。一定要加withoutEnlargement: true。默认 sharp 会把小图放大到目标尺寸结果就是一张糊图。加上这个参数原图比目标小就保持原样不做无意义的放大。列表页缩略图我一般用fit: inside让长边不超过某个值既控制体积又不强行改变比例。水印composite 合成水印本质是把一张图叠到另一张上sharp 用composite做它接收一个数组可以叠多层constsharprequire(sharp);asyncfunctionwatermark(input,logoPath){returnsharp(input).resize({width:1200,withoutEnlargement:true}).composite([{input:logoPath,// 水印图也可以是 Buffergravity:southeast,// 放右下角// blend 默认 over水印图本身带透明度就能实现半透明叠加},]).jpeg({quality:85}).toBuffer();}如果要文字水印sharp 本身不排版文字常见做法是用 SVG 当作合成层——SVG 里写文字libvips 会把它栅格化constsharprequire(sharp);asyncfunctiontextWatermark(input,text){constsvgsvg width400 height60 style .t { fill: #ffffff; fill-opacity: 0.75; font-size: 32px; font-family: sans-serif; font-weight: 700; } /style text x10 y42 classt${text}/text /svg;returnsharp(input).composite([{input:Buffer.from(svg),gravity:southeast},]).toBuffer();}注意${text}直接拼进 SVG 有 XML 注入风险用户可控的文字务必先做转义把、、、引号换成实体。另外服务器上要有对应字体容器镜像里经常缺中文字体导致中文水印渲染成方框——记得在 Dockerfile 里装上fonts-noto-cjk之类的字体包。格式转换WebP/AVIF 与质量取舍这是 sharp 最能省成本的地方。同一张图转成 WebP 通常比 JPEG 小 25%~35%AVIF 还能再小一截constsharprequire(sharp);asyncfunctionconvert(input){// WebP兼容性好、编码快日常首选constwebpawaitsharp(input).webp({quality:78})// 78~82 是画质/体积的甜点区.toBuffer();// AVIF体积更小但编码慢很多CPU 敏感场景要掂量constavifawaitsharp(input).avif({quality:50,effort:4})// effort 越高越小越慢0~9.toBuffer();// PNG无损适合图标/透明图用 palette 压缩体积constpngawaitsharp(input).png({compressionLevel:9,palette:true}).toBuffer();return{webp,avif,png};}工程上的关键判断WebP 是当前默认最优解。编码速度和 JPEG 一个量级体积明显更小主流浏览器全支持。AVIF 编码是 CPU 黑洞。effort调高时单张图编码可能要几百毫秒到几秒放在同步请求路径上会拖垮吞吐。真要上 AVIF一定异步预生成 缓存别在用户请求时现编。质量参数不是越高越好。JPEG/WebP 的 quality 从 90 往上体积暴涨但肉眼几乎无差别。多数场景 78~85 足够。别忘了根据请求头Accept里有没有image/webp、image/avif来协商返回哪种格式做好降级。旋转与 EXIF 方向一个必踩的坑手机拍的照片实际像素是横躺的靠 EXIF 里的 Orientation 标记告诉软件「该转多少度显示」。如果你的处理链不管这个resize 之后方向标记丢了图片就会歪。sharp 的解法是无参数rotate()constsharprequire(sharp);asyncfunctionfixOrientation(input){returnsharp(input).rotate()// 不传角度 读 EXIF Orientation 自动摆正.resize({width:1000}).toBuffer();}rotate()必须放在resize()之前先把图摆正再缩放尺寸计算才对。无参rotate()会按 EXIF 把图物理旋转到正确方向并清掉 Orientation 标记后续任何软件都不会再二次旋转。顺带一提隐私EXIF 里可能带 GPS、拍摄时间、设备型号。sharp 默认输出会剥离大部分元数据除非你显式.withMetadata()这对用户隐私是好事。如果业务需要保留方向但去掉 GPS可以.rotate()之后再输出方向已经落到像素上元数据丢了也不影响显示。封装成 Express 接口把上面的能力串成一个能对外的服务。核心是流式响应 缓存 参数校验。constexpressrequire(express);constsharprequire(sharp);constcryptorequire(crypto);constappexpress();// 简单的内存缓存生产建议换 Redis / 本地磁盘 / CDN 回源constcachenewMap();// 白名单避免用户传任意尺寸打爆内存constALLOWED_WIDTHSnewSet([100,200,400,800,1200]);app.get(/thumb,async(req,res){try{constsrcString(req.query.src||);constwidthNumber(req.query.w)||400;constformat[webp,jpeg,png].includes(req.query.f)?req.query.f:webp;if(!ALLOWED_WIDTHS.has(width)){returnres.status(400).json({error:unsupported width});}constkeycrypto.createHash(sha1).update(${src}|${width}|${format}).digest(hex);if(cache.has(key)){res.type(image/${format});res.set(X-Cache,HIT);returnres.end(cache.get(key));}// 实际项目里 src 应走白名单/签名别直接让用户传任意 URL/路径constinputBufferawaitloadImage(src);letpipelinesharp(inputBuffer).rotate().resize({width,withoutEnlargement:true});pipelineformatwebp?pipeline.webp({quality:80}):formatpng?pipeline.png({compressionLevel:9}):pipeline.jpeg({quality:82});constoutawaitpipeline.toBuffer();cache.set(key,out);res.type(image/${format});res.set(Cache-Control,public, max-age31536000, immutable);res.set(X-Cache,MISS);res.end(out);}catch(err){console.error(err);res.status(500).json({error:process failed});}});asyncfunctionloadImage(src){// 从对象存储/本地磁盘/白名单 URL 读取返回 Buffer// 这里省略务必做来源校验thrownewError(implement me);}app.listen(3000,()console.log(image service on :3000));几个关键点参数白名单。宽度、格式都用白名单卡死。绝不能让用户传w99999让你现场生成一张一亿像素的图。缓存 key 用输入参数哈希。同样的 src尺寸格式第二次直接命中。生产环境这层缓存应该在 CDN 对象存储Node 进程只负责首次生成。Cache-Control: immutable。缩略图 URL 只要参数不变结果就不变让浏览器和 CDN 长期缓存。来源校验。src让用户随便传是 SSRF 高危洞。要么用内部 ID 映射要么对 URL 做签名。工程边界这才是决定能不能上线的部分前面的代码谁都能跑通但直接丢到线上多半会出事。sharp 底层是 libvips 原生代码几个边界必须清楚1. 大图会吃爆内存。libvips 虽然省内存但解码到内存的临时数据仍和「像素总数」正相关不是文件体积。一张 100KB 的 PNG 可能解压出 20000×20000 的画布所谓 decompression bomb。务必用sharp(input, { limitInputPixels: 268402689 })限制输入像素上限默认约 0.27 亿即 16383×16383超限直接拒绝别让一张恶意图打爆整个进程。2. CPU 密集会阻塞事件循环吗好消息sharp 的核心运算跑在 libvips 的线程池里libuv threadpool不占 Node 主线程所以单张处理不会像纯 JS 计算那样卡死事件循环。但坏消息是——线程池默认只有 4 个线程UV_THREADPOOL_SIZE并发一上来图片任务会排队也会和其它用 threadpool 的操作DNS、fs、crypto抢资源。3. 并发要主动限流。别以为 sharp 不阻塞主线程就能无限并发。每个并发任务都在消耗内存和 CPU 核心100 个请求同时进来解码大图内存分分钟 OOM。正确姿势是用p-limit或队列把并发压到「CPU 核数 × 1~2」这个量级constpLimitrequire(p-limit);constsharprequire(sharp);// 并发上限 CPU 核数避免同时解码太多大图导致 OOMconstlimitpLimit(require(os).cpus().length);// sharp 自身也可以关掉内部并发把「一张图用几个线程」交给上层控制sharp.concurrency(1);asyncfunctionsafeProcess(buffer){returnlimit(()sharp(buffer).rotate().resize({width:800,withoutEnlargement:true}).webp({quality:80}).toBuffer());}sharp.concurrency(1)让单张图只用一个 libvips 线程把「用几个核」的决策权交给上层的p-limit整体更可控。反过来如果你处理的图都很大、并发很低可以调大 sharp 内部并发让单张更快。4. 要不要放主进程 / 何时上队列。我的经验分界线实时、轻量、可缓存用户上传头像立即出缩略图、请求量不大放在 API 进程里同步处理没问题配合p-limit限流 结果缓存就够。重、批量、可延迟一次上传要生成 5 种尺寸 × 3 种格式、AVIF 编码、几千张批处理一定拆出去。上一个消息队列BullMQ / RabbitMQAPI 只落原图 入队独立的 worker 进程消费。这样图片处理的 CPU 尖峰不会拖垮你的 API 响应时间worker 还能独立横向扩容。判断标准就一句话图片处理的耗时和资源占用会不会影响到你 API 的 P99 延迟。会就异步化。5. 原生依赖的坑。sharp 带预编译二进制跨平台/跨架构部署要注意本地 macOS 装的 sharp 直接拷进 Linux 容器会跑不起来。用 Docker 多阶段构建时npm install要在目标平台的镜像里跑或者用--platform明确指定。CI 里也别把node_modules缓存跨平台复用。6. 什么时候干脆别自己写。如果只是想快速把图压一压、转个格式、抠个背景不想维护一整套服务和 worker 集群直接用现成的图片处理工具/服务也完全合理比如 squoosh、ImageMagick、tudingai.cn 这类在线或命令行工具够用就是最优解。自建 sharp 服务的价值在于「深度定制 大规模 成本可控」需求还没到那个量级时别过度工程化。小结用 sharp 搭图片服务代码层面并不复杂——resize的 fit 模式、composite水印、格式转换的质量取舍、rotate()修 EXIF 方向这几块拼起来就是一套完整能力。真正拉开差距的是工程边界输入像素限制防炸内存、p-limit主动限流、大批量任务拆队列、跨平台原生依赖处理。一句话总结选型逻辑能力用 sharp稳定性靠限流和队列成本靠缓存和格式转换。把这三件事做扎实一个能扛住生产流量的图片处理服务就成了。