image-compression

平台说明

• 可选的辅助插件可能在某些环境中有所帮助，但不得将其视为此技能的必需项。

图像压缩

鸣谢：由 Peter Bamuhigire 分享，techguypeter.com，+256 784 464178。

适用场景

• 使用 Squoosh 在客户端压缩图像后再上传，并以 Canvas 作为回退方案、以 Sharp 在服务端进行验证。适用于需要最大宽度 1920px、最大大小 512KB、无感用户体验和一致压缩统计数据的 Web 应用。

生成的证据

类别	产物	格式	示例
性能	图像压缩策略	Markdown 文档，涵盖 Squoosh 客户端目标、Canvas 回退方案和 Sharp 服务端验证预算	docs/images/compression-policy.md

参考资料

• 阅读下方核心工作流后，可使用 references/ 目录了解详细信息。

采用混合图像压缩流程：

• 客户端首选： Squoosh（WASM）
• 客户端回退： Canvas API
• 服务端安全保障： Sharp

常见默认值： 长边上限 1920 px，规范输出最大值 512 KB，质量 75 （可在明确的质量下限内调低）。如果渲染场景、透明度或小尺寸可读性有要求，则以产品配置为准。

适用场景

✅ 上传用户图像且必须减少带宽占用的 Web 应用 ✅ 需要无感用户体验（无需用户操作） ✅ 希望使用现代编解码器，但必须兼容旧版浏览器

不适用场景

❌ 仅服务端的批处理管线（直接使用 Sharp） ❌ 大规模且需要复杂变换的媒体处理（使用 ImageMagick/FFmpeg）

核心规则

1. 保持宽高比；绝不放大图像。
2. 目标最大宽度为 $1920$px，最大大小为 $512$ KB。
3. 从质量 $75$ 开始；逐步降低以满足大小要求。
4. 优先使用兼容性更好的 JPEG；如果大小仍超限，则尝试 WebP。
5. 记录压缩统计数据（压缩比、节省量、处理时间）。
6. 将客户端提供的 MIME 类型、扩展名、尺寸和压缩后字节视为不可信提示。
7. 在服务端，根据字节检测内容，限制尺寸、像素数和资源占用，完整解码，剥离元数据，并重新编码为规范的允许列表内的栅格格式。
8. 为 logo/favicon 保留 alpha；绝不强制将透明图稿转换为 JPEG。
9. 将规范输出存储在公有 Web 根目录之外的随机不透明密钥下，然后仅通过授权的交付策略发布。

决策流程

1. 尝试客户端压缩（Squoosh）
   • 调整大小 → 压缩 → 检查大小。
   • 逐步降低质量，直至满足大小限制。
   • 如果仍然超限，则尝试 WebP。
2. 客户端回退（Canvas）
   • 调整大小 → 转换为 Blob 格式的 JPEG → 必要时降低质量。
3. 权威服务端管线（Sharp、GD、ImageMagick 或同类工具）
   • 解码前限制入口数据；根据字节检测 MIME 类型，并要求解码器成功解码。
   • 拒绝宽度、高度、总像素数、帧数、内存或处理时间超限的图像。
   • 解码、调整方向、剥离元数据、不放大地调整大小，并根据像素进行规范化。
   • 必要时保留 alpha；重新编码后强制检查最终尺寸和字节限制。
   • 处理失败时，绝不回退到存储原始文件。

实施步骤（概述）

1. 客户端压缩服务
   • 提供 compressImage(file, options)。
   • 使用动态导入加载 Squoosh。
   • 出错时回退到 Canvas。
2. 上传钩子/处理程序
   • 验证输入是否为图像。
   • 无感地进行压缩。
   • 上传压缩后的 Blob。
3. 服务端中间件
   • 使用 Sharp 强制执行限制。
   • 如果仍然超限，则返回 413。
   • 将压缩统计数据附加到日志中。

必需默认值

• maxWidth：1920
• maxHeight：1920
• maxSize：$512 * 1024$
• quality：75
• minDimensions：200x200（服务端）

反模式

• ❌ 跳过服务端验证
• ❌ 失败时不记录日志就上传原始文件
• ❌ 放大图像
• ❌ 使用阻塞式 UI（必须对用户无感）

参考资料（按需加载）

• 客户端实现：references/client.md
• 客户端用法示例：references/client-usage.md
• 服务端中间件 + 路由：references/server.md
• 存储适配器（S3/本地）：references/storage.md
• 安全检查：references/security.md
• 托管式 SaaS 背景图/Logo/favicon 生命周期：saas-managed-visual-assets
• 监控与分析：references/monitoring.md
• 性能目标：references/performance.md
• 质量示例：references/quality-metrics.md
• 环境变量：references/env.md
• Docker（Sharp）：references/docker.md
• 实施检查清单：references/implementation-checklist.md

输出预期

• 客户端压缩通常在 $100$–$500$ ms 内完成
• 服务端压缩通常耗时 $50$–$200$ ms
• 带宽减少 $85$–$97%$

检查清单

反模式

• 信任客户端输出。修复方法：在服务端解码并验证媒体。
• 仅将 file.type、扩展名或魔数视为权威依据。修复方法：要求进行内容检测、成功完成有界解码和规范化重新编码。
• 未经同意，失败后上传原始文件。修复方法：显示可恢复的错误，并记录原因。
• 放大较小的源文件。修复方法：保留其原始尺寸。
• 压缩期间阻塞界面。修复方法：提供异步进度、取消和重试。
• 对所有格式使用同一个质量值。修复方法：按编解码器调整，并检查有代表性的图像。
• 将透明 Logo/favicon 转换为 JPEG。修复方法：使用 PNG 或支持 Alpha 通道的 WebP。
• 使用原始文件名为持久对象命名。修复方法：生成不透明的随机键；如有需要，仅将原始名称作为受保护的元数据存储。

能力约定

先读取并搜索上传路径。仅在获得授权后编辑；在条件允许时，执行编解码器、大小限制、畸形文件和服务端验证测试。网络访问不是验证依赖项的必要条件。

• 客户端：Squoosh 为主要方案 + Canvas 后备方案
• 客户端：强制执行大小/尺寸限制
• 服务端：权威内容检测、有界解码、规范化重新编码和最终限制
• 服务端：像素数/帧数/时间/内存预算及畸形文件/多格式文件测试语料库
• 透明度：为 Logo/favicon 配置保留 Alpha 通道
• 存储：随机且不可变的键、私有源站、受控交付和清理
• 日志：压缩统计信息和处理时间
• 存储：保存带元数据的图像
• 测试：JPEG/PNG/WebP、大图、移动设备

输入

资料	必需？	用途
源图像、显示尺寸、质量目标、格式和交付限制	是	选择安全的优化方式

输出

• 生成优化后的资源，并提供尺寸、质量、格式和渲染效果的测量证据。

降级模式

无法进行视觉检查或目标渲染时：保留原始文件，并将质量对比标记为未经验证。

工作流

盘点用途，选择格式和尺寸，以非破坏性方式压缩，渲染有代表性的状态，对比质量和尺寸，然后更新引用。