imgmin

本地图片批量压缩工具，TinyPNG 的本地替代——纯本地处理，不上传、无额度限制。

基于 sharp（PNG palette 量化走 libimagequant，效果接近 pngquant；JPEG 走 mozjpeg）。

作者：Youzi

安装与运行

# 免安装，直接 npx 运行
npx youzi-imgmin ./images

# 或全局安装后用 imgmin 命令
npm i -g youzi-imgmin
imgmin ./images

本地开发

# 在仓库目录内
pnpm install
node compress.mjs <文件或目录...> [选项]

# 链接成全局命令调试
pnpm link --global
imgmin ./images

默认行为（增量原地压缩）

• 首次见到某文件：备份其原始版到 .imgmin/originals/（每文件仅一次），再压缩并原地覆盖。
• 再次运行：通过 .imgmin/manifest.json 比对，已压缩过且未改动的文件自动跳过——不会被二次压缩劣化。
• 备份、清单、报告统一写入 项目根/.imgmin/，并自动加入 .gitignore（不入库）。

node compress.mjs ./images   # 首次全压；之后再跑只压新增/改动的图

产物（项目根，即 git 仓库根；非 git 项目退回当前目录）：

.imgmin/
├── originals/<相对路径>     # 原始文件备份，每个文件只存一份
├── manifest.json           # 增量清单：记录每个文件原始/压缩后的 hash 与大小
└── report-<时间>.json      # 本次运行的前后对比报告

判定逻辑基于内容 hash：当前文件 == 清单里记录的「压缩后 hash」即视为已压、跳过；文件被替换（hash 变了）会重新备份并压缩。

选项

| 选项 | 说明 | |---|---| | --mode <lossy\|lossless> | 压缩档，默认 lossy（有损，体积优先，类 TinyPNG） | | -q, --quality <1-100> | 有损质量，默认 80（仅 lossy 生效） | | -f, --force | 忽略清单，对已压缩文件也重压（从 originals/ 原始重压，避免二次劣化） | | -o, --out <dir> | 改为输出到目录、不动原图（关闭原地覆盖/备份/清单） | | --no-backup | 原地覆盖但不备份原始文件 | | --webp | 额外导出一份 .webp | | --no-recursive | 目录不递归 | | -h, --help | 帮助 |

支持格式：png / jpg / jpeg / webp。

示例

# 默认：增量压缩（已压过的跳过）
node compress.mjs ./images

# 指定多个文件 + 质量
node compress.mjs a.png b.jpg -q 70

# 无损（保真，仅去冗余）
node compress.mjs ./images --mode lossless

# 从原始备份按当前档重压全部（换了质量/模式时用）
node compress.mjs ./images --force --mode lossless

# 不动原图，输出到 dist/
node compress.mjs ./images -o dist

# 顺带导出 webp
node compress.mjs ./images --webp

报告格式（report-<时间>.json）

{
  "tool": "youzi-imgmin",
  "generatedAt": "2026-05-27T13:29:53.694Z",
  "mode": "lossy",
  "quality": 80,
  "force": false,
  "target": "in-place",
  "totals": { "candidates": 2, "compressed": 1, "kept": 0, "skippedAlready": 1, "failed": 0, "before": 239299, "after": 25500, "saved": 213799, "savedPct": 89.3 },
  "items": [
    { "file": "assets/banner.jpg", "before": 239299, "after": 25500, "savedPct": 89.3, "kept": false, "status": "ok" },
    { "file": "assets/login-logo.png", "before": 83425, "after": 83425, "savedPct": 0, "status": "skipped-already" }
  ]
}

恢复备份

.imgmin/originals/ 按相对项目根的路径镜像保存原始文件，直接拷回即可还原：

# 还原单个文件
cp .imgmin/originals/assets/banner.jpg assets/banner.jpg

# 还原全部（在项目根执行）
cp -R .imgmin/originals/. .

说明

• 增量去重：原始文件每个只备份一份；已压缩且未改动的文件再次运行会跳过，不会二次有损压缩劣化。
• 改动即更新：文件内容变了（hash 不一致）会被当作新原始，重新备份并压缩。
• 重压用 --force：换了质量/模式想重压时加 --force，会从 originals/ 的原始版本重压，而不是在已压版上叠加。
• 压完更大就保留原图：某些已优化的小图重编码后反而变大，此时自动保留原文件（报告里 kept: true）。
• lossy vs lossless：lossy 类 TinyPNG，画质轻微损失换最大压缩率；lossless 不改像素只去冗余，体积减少较少但完全保真。JPEG 无真正无损，lossless 档用 q95 + mozjpeg 重编码。