au_tinypng

基于 TinyPNG Web 接口的本地图片压缩工具。进入图片目录后执行命令，它会递归扫描当前目录下的图片，压缩成功后直接替换原图，并记录处理状态，方便失败后重复执行。

功能

• 递归处理当前执行目录下的子目录图片。
• 支持 .jpg、.jpeg、.png、.gif。
• 单张图片最大支持约 5MB，超过会跳过并记录原因。
• 压缩成功后直接覆盖原图片，不再生成额外输出目录。
• 通过压缩后 hash 精确判断图片状态，并在 hash 变化时结合历史输出大小保守判断是否需要重新压缩。
• 压缩失败的图片会记录失败次数，下次执行继续重试。
• 同一张图片同一 hash 连续失败达到上限后会自动跳过，避免一直重复失败。
• 命令行会展示进度条、当前进度、压缩后占比和节省比例。

安装

全局安装：

npm i au_tinypng -g

项目内安装（开发依赖）：

npm i au_tinypng -D

使用

进入需要压缩图片的目录后，根据安装方式执行对应命令。

建议始终在项目根目录执行压缩命令。缓存文件会生成在当前执行目录中，如果从不同子目录运行，可能会在多个位置生成 .au_tinypng-compress-cache.json。

全局安装后

直接执行：

au_tinypng

指定压缩间隔和失败重试次数：

au_tinypng --delay 3000 --max-retries 5

项目内安装后

通过 npx 执行项目本地安装的命令：

npx au_tinypng

指定压缩间隔和失败重试次数：

npx au_tinypng --delay 3000 --max-retries 5

--delay 默认为 2000 毫秒，--max-retries 默认为 3 次，两种安装方式支持的参数完全一致。

处理规则

执行命令时，工具会以当前目录为根目录递归查找图片。

压缩成功后，压缩后的图片会直接写回原文件路径。例如：

images/banner.png

压缩完成后仍然是：

images/banner.png

工具会在当前执行目录生成缓存文件：

.au_tinypng-compress-cache.json

缓存文件会记录每张图片的相对路径、压缩前 hash、压缩后 hash、输入/输出大小、压缩结果、失败次数和最后更新时间。

再次执行时：

• 如果当前图片 hash 等于缓存中的压缩后 hash，说明已经压缩成功，会直接跳过。
• 如果 hash 不同但存在有效的历史输出大小，会计算 历史 outputSize / 当前文件大小：
  • 比例小于 60%，说明当前图片仍有明显压缩空间，会重新压缩。
  • 比例大于或等于 60%，会保守视为已经压缩并跳过。
• 如果历史 outputSize 缺失、无效，或者当前图片为空文件，不使用大小兜底，会重新尝试压缩。
• 如果图片上次失败但还没达到失败上限，会继续尝试压缩。
• 如果同一张图片同一 hash 已连续失败达到上限，会跳过，避免死循环。

输出示例

压缩中：

[######------------------] 1/4 25.00% 压缩中：images/组 3@2x_副本.png

压缩成功：

[完成] images/组 3@2x_副本.png | 364 KB -> 73.1 KB | 压缩后 20.08% | 节省 79.92%

压缩失败：

[失败] images/demo.png | Request is invalid

跳过已压缩图片：

[images/banner.png] 已压缩成功，跳过。

达到失败上限：

[images/error.png] 已连续失败 3 次，跳过。可修改图片后重试，或使用 --max-retries 提高上限。

注意事项

• 压缩成功会直接替换原图，建议在 Git 工作区或已有备份的目录中使用。
• 当前脚本本质上调用 TinyPNG 的 Web 接口，请合理使用。
• 图片过大、格式异常、接口限制或网络问题都可能导致压缩失败。
• 如果某张图片一直失败，可以手动处理该图片，或者调整 --max-retries 后再次执行。
• 如果想让某张已压缩图片重新参与压缩，可以修改图片内容，或谨慎删除 .au_tinypng-compress-cache.json 中对应记录。

免责声明

该工具仅用于学习和提升本地图片处理效率。如有商业用途，请购买 TinyPNG 官方服务。

作者：龍