@zhaoshijun/compress

一个高效的图片压缩工具箱，包含命令行工具 (CLI) 和 Vite 插件。基于 sharp 构建，提供高性能的图片压缩方案。

特性

• 🚀 高性能：基于 sharp，速度极快。
• 🛠 双模支持：
  • CLI：批量扫描并压缩项目图片。
  • Vite 插件：在 vite build 构建时自动压缩引用的图片资源。
• ⚙️ 灵活配置：支持配置文件 (compress.config.js)，可精细控制压缩参数。
• 🛡 安全可靠：支持备份原文件，默认不覆盖源文件（CLI 模式输出到指定目录）。
• 📦 智能缓存：Vite 插件基于内容 Hash 缓存，避免重复压缩，提升构建速度。
• 💧 水印功能：支持文本水印、图片水印（单个/平铺），可自定义透明度、位置、尺寸等参数。
• 🔒 隐私保护：默认去除图片元数据（拍摄时间、地点等），支持保留元数据选项。

安装

npm install @zhaoshijun/compress --save-dev
# 或
yarn add @zhaoshijun/compress -D
# 或
pnpm add @zhaoshijun/compress -D

命令行工具 (CLI)

CLI 工具用于批量扫描并压缩本地图片文件。

快速开始

1. 初始化配置 (可选) 生成默认的 compress.config.js 文件：

   npx @zhaoshijun/compress init

2. 运行压缩 扫描当前目录及子目录下的图片并压缩：

   npx @zhaoshijun/compress

命令行选项

| 选项 | 简写 | 描述 | | ----------------- | ---- | ---------------------------------------------------- | | --config <path> | -c | 指定配置文件路径 | | --backup | | 启用备份模式（将原文件复制为 .backup） | | --dry-run | | 演练模式，仅列出将要处理的文件，不进行实际压缩和写入 | | --quiet | -q | 静默模式，仅输出错误信息 | | --watermark | -w | 启用水印（使用配置文件中的水印设置） | | --keep-metadata | | 保留图片元数据（拍摄时间、地点等） | | --output <dir> | -o | 输出目录 | | --help | -h | 显示帮助信息 |

水印命令选项

| 选项 | 描述 | | ---- | ---- | | --watermark-mode <mode> | 水印模式 (text/image/tiled) (default: "text") | | --watermark-text <text> | 水印文本 | | --watermark-image <path> | 水印图片路径 | | --watermark-opacity <opacity> | 水印透明度 (0-1) | | --watermark-density <density> | 水印密度 (1-10) | | --watermark-color <color> | 水印颜色 (hex 或 rgba) | | --watermark-font-size <size> | 水印字体大小 | | --watermark-width <width> | 水印图片宽度 | | --watermark-height <height> | 水印图片高度 | | --watermark-position <position> | 水印位置 (top-left/top-right/bottom-left/bottom-right/center/custom) | | --watermark-padding <padding> | 水印边距 | | --watermark-angle <angle> | 水印倾斜角度 | | --watermark-spacing-x <spacing> | 水印水平间隔 | | --watermark-spacing-y <spacing> | 水印垂直间隔 |

示例

# 仅预览将要压缩的文件
npx @zhaoshijun/compress --dry-run

# 使用指定配置文件并开启静默模式
npx @zhaoshijun/compress -c ./config/compress.js -q

# 压缩图片并添加文本水印
npx @zhaoshijun/compress -w --watermark-text "Copyright 2024"

# 压缩图片并添加自定义文本水印
npx @zhaoshijun/compress -w --watermark-text "My Watermark" --watermark-opacity 0.3 --watermark-color "#ff0000"

# 压缩图片并添加图片水印
npx @zhaoshijun/compress -w --watermark-mode image --watermark-image "./logo.png"

# 压缩图片并添加平铺水印
npx @zhaoshijun/compress -w --watermark-mode tiled --watermark-image "./copyright.png"

# 压缩图片并保留元数据
npx @zhaoshijun/compress --keep-metadata

# 压缩图片并指定输出目录
npx @zhaoshijun/compress --output ./compressed

水印功能

支持三种水印模式：文本水印、单个图片水印、平铺图片水印。

单独添加水印

如果只需要给图片添加水印而不进行压缩，可以使用 watermark 命令：

# 文本水印
npx @zhaoshijun/compress watermark --watermark-text "Copyright 2024"

# 自定义文本水印参数
npx @zhaoshijun/compress watermark --watermark-text "Confidential" --watermark-opacity 0.7 --watermark-density 5 --watermark-color "rgba(255,0,0,0.5)"

# 单个图片水印
npx @zhaoshijun/compress watermark --watermark-mode image --watermark-image "./logo.png"

# 自定义图片水印位置和尺寸
npx @zhaoshijun/compress watermark --watermark-mode image --watermark-image "./brand-logo.png" --watermark-position bottom-right --watermark-padding 20 --watermark-opacity 1

# 平铺图片水印
npx @zhaoshijun/compress watermark --watermark-mode tiled --watermark-image "./copyright.png"

# 自定义平铺水印参数
npx @zhaoshijun/compress watermark --watermark-mode tiled --watermark-image "./copyright.png" --watermark-opacity 0.15 --watermark-width 100 --watermark-height 100 --watermark-angle -30 --watermark-spacing-x 300 --watermark-spacing-y 300

# 指定输出目录
npx @zhaoshijun/compress watermark --watermark-text "Watermark" --output ./output

水印参数说明

文本水印参数

| 参数 | 说明 | 默认值 | 范围 | | ---- | ---- | ------ | ---- | | mode | 水印模式 | 'text' | text/image/tiled | | text | 水印文本内容 | '' | 必填 | | opacity | 水印透明度 | 1 | 0-1 | | density | 水印密度（平铺数量） | 3 | 1-10 | | color | 水印颜色 | '#ffffff' | hex 或 rgba | | fontSize | 水印字体大小 | 24 | 正整数 |

单个图片水印参数

| 参数 | 说明 | 默认值 | 范围 | | ---- | ---- | ------ | ---- | | mode | 水印模式 | 'text' | text/image/tiled | | imagePath | 水印图片路径 | '' | 必填 | | opacity | 水印透明度 | 1 | 0-1 | | width | 水印宽度 | null | 正整数 | | height | 水印高度 | null | 正整数 | | position | 水印位置 | 'top-left' | top-left/top-right/bottom-left/bottom-right/center/custom | | padding | 水印边距 | 10 | 正整数 | | x | 自定义 X 坐标 | 0 | 正整数 | | y | 自定义 Y 坐标 | 0 | 正整数 |

平铺图片水印参数

| 参数 | 说明 | 默认值 | 范围 | | ---- | ---- | ------ | ---- | | mode | 水印模式 | 'text' | text/image/tiled | | imagePath | 水印图片路径 | '' | 必填 | | opacity | 水印透明度 | 1 | 0-1 | | width | 水印宽度 | null | 正整数 | | height | 水印高度 | null | 正整数 | | angle | 倾斜角度 | -30 | -180 到 180 | | spacingX | 水平间隔 | 100 | 正整数 | | spacingY | 垂直间隔 | 100 | 正整数 |

Vite 插件

该插件仅在 vite build 生产构建模式下生效，会自动压缩项目中引用的图片资源，并替换构建产物中的引用路径。

配置

在 vite.config.js 中引入并添加插件：

import { defineConfig } from "vite";
import { compressVitePlugin } from "@zhaoshijun/compress";

export default defineConfig({
  plugins: [
    compressVitePlugin({
      // 1. JPEG 压缩选项
      jpegOptions: {
        quality: 75,
        progressive: true,
        mozjpeg: true
      },

      // 2. PNG 压缩选项
      pngOptions: {
        compressionLevel: 9,
        palette: true,
        effort: 7
      },

      // 3. WebP 压缩选项
      webpOptions: {
        quality: 80,
        effort: 4
      },

      // 4. 尺寸限制（可选）
      resize: {
        maxWidth: 1024,
      },

      // 5. 水印配置
      watermark: {
        text: 'Copyright 2024',
        opacity: 0.5,
        density: 3,
        color: '#ffffff',
        fontSize: 24
      },

      // 6. 控制缓存
      cache: false,
    }),
  ],
});

插件特性

• 自动替换：压缩后的文件会自动添加 .min 后缀（如 logo.min.png），并自动更新 JS/CSS 中的引用路径。
• 构建缓存：默认启用缓存（node_modules/.cache/@zhaoshijun/compress），只有当图片内容发生变化时才会重新压缩。
• 开发环境友好：vite dev 模式下插件不运行，不影响开发服务器启动速度。

配置文件详解

项目根目录下的 compress.config.js 用于统一管理压缩配置。

// compress.config.js
module.exports = {
  // [CLI专用] 输入文件模式，支持 glob 数组
  // 默认扫描所有子目录下的 jpg, jpeg, png, webp
  input: ["**/*.{jpg,jpeg,png,webp}"],

  // [CLI专用] 输出目录
  // 默认输出到当前目录下的 compressed 文件夹，保持原目录结构
  output: "./compressed",

  // 尺寸调整 (可选)
  // 注意：scale 与 maxWidth/maxHeight 互斥，优先使用 maxWidth/maxHeight
  resize: {
    maxWidth: 1920, // 最大宽度，保持纵横比
    // maxHeight: 1080, // 最大高度
    // scale: 0.8       // 缩放比例 (0-1)
  },

  // JPEG 专属配置
  jpegOptions: {
    quality: 88, // 质量 (1-100)，默认 88
    progressive: false, // 渐进式 JPEG，默认 false
    mozjpeg: false, // 使用 mozjpeg 编码器，默认 false
    trellisQuantisation: false, // Trellis 量化，默认 false
    overshootDeringing: false, // 过冲去环，默认 false
    optimiseScans: false, // 优化扫描，默认 false
    optimiseCoding: false // 优化编码，默认 false
  },

  // PNG 专属配置
  pngOptions: {
    compressionLevel: 9, // 压缩等级 0-9，默认 9
    palette: true, // 是否启用调色板量化，默认 true (显著减小体积)
    adaptiveFiltering: false, // 自适应过滤，默认 false
    progressive: false, // 渐进式 PNG，默认 false
    effort: 7 // 压缩努力程度 1-10，默认 7
  },

  // WebP 专属配置
  webpOptions: {
    quality: 88, // 质量 (1-100)，默认 88
    alphaQuality: 80, // 透明度质量 (0-100)，默认 80
    lossless: false, // 无损压缩，默认 false
    nearLossless: false, // 近无损压缩，默认 false
    smartSubsample: false, // 智能子采样，默认 false
    effort: 4 // 压缩努力程度 0-6，默认 4
  },

  // 输出文件名后缀
  // 默认 '.min'，例如 image.jpg -> image.min.jpg
  suffix: ".min",

  // [CLI专用] 是否备份原文件
  backup: false,

  // 元数据处理
  keepMetadata: false, // 是否保留图片元数据（拍摄时间、地点等），默认 false（去除元数据）

  // 水印配置
  watermark: {
    mode: 'text', // 水印模式：text/image/tiled
    text: '', // 水印文本内容，留空则不添加水印
    imagePath: '', // 水印图片路径（image/tiled 模式）
    opacity: 1, // 水印透明度 (0-1)
    density: 3, // 水印密度 (1-10)，数值越大水印越多
    color: '#ffffff', // 水印颜色，支持 hex 或 rgba 格式
    fontSize: 24, // 水印字体大小
    width: null, // 水印图片宽度（image/tiled 模式）
    height: null, // 水印图片高度（image/tiled 模式）
    position: 'top-left', // 水印位置（image 模式）：top-left/top-right/bottom-left/bottom-right/center/custom
    padding: 10, // 水印边距（image 模式）
    x: 0, // 自定义 X 坐标（position 为 custom 时）
    y: 0, // 自定义 Y 坐标（position 为 custom 时）
    angle: -30, // 倾斜角度（tiled 模式）
    spacingX: 100, // 水平间隔（tiled 模式）
    spacingY: 100 // 垂直间隔（tiled 模式）
  },

  // [Vite插件专用] 配置
  vite: {
    cache: true, // 是否启用构建缓存，默认 true
  },
};

支持的格式

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)

默认排除

CLI 工具默认会排除以下目录：

• node_modules/
• dist/
• .git/
• coverage/

常见问题

Q: 如何处理损坏的图片？ A: 工具会自动检测并跳过损坏的图片，输出警告信息，不会中断整个压缩流程。

Q: Vite 插件会修改源代码中的图片吗？ A: 不会。Vite 插件仅在构建过程中处理资源，生成的压缩图片位于构建输出目录（如 dist/assets），源代码保持不变。

Q: 水印会影响图片质量吗？ A: 水印是在图片压缩后添加的，不会影响图片本身的压缩质量。水印的透明度可以通过 opacity 参数调整，建议设置为 0.3-0.7 之间以获得最佳效果。

Q: 支持哪些水印模式？ A: 支持三种水印模式：

• 文本水印：添加文字水印，可自定义文本、颜色、字体大小等
• 单个图片水印：在指定位置添加单个图片水印，支持 6 种预设位置和自定义坐标
• 平铺图片水印：在整个图片上平铺水印图片，支持旋转和间隔设置

Q: 水印密度如何设置？ A: 水印密度 density 参数控制水印的平铺数量，范围是 1-10。数值越大，水印越密集。默认值为 3，适合大多数场景。

Q: 可以只添加水印不压缩吗？ A: 可以。使用 watermark 命令可以单独给图片添加水印而不进行压缩，输出到 ./watermarked 目录。

Q: 水印颜色支持哪些格式？ A: 水印颜色支持十六进制格式（如 #ffffff）和 RGBA 格式（如 rgba(255,255,255,0.5)）。

Q: 图片水印支持哪些格式？ A: 水印图片支持 JPEG、PNG、WebP、GIF、TIFF、SVG 等常见格式。

Q: 如何去除图片元数据？ A: 默认情况下，压缩图片时会自动去除所有元数据（包括拍摄时间、GPS 位置、相机信息等）。如果需要保留元数据，可以使用 --keep-metadata 选项或在配置文件中设置 keepMetadata: true。

Q: 去除元数据有什么好处？ A: 去除元数据有以下好处：

• 隐私保护：防止拍摄时间、地点等敏感信息泄露
• 文件体积减小：元数据占用额外空间，去除后文件更小
• 加载速度提升：更小的文件加载更快
• 带宽节省：减少网络传输数据量

Q: 什么时候需要保留元数据？ A: 以下场景可能需要保留元数据：

• 摄影作品集：需要保留拍摄参数和版权信息
• 图库上传：某些图库要求保留元数据
• 档案管理：需要记录拍摄时间和设备信息
• 法律要求：某些场景需要保留原始元数据

Q: 如何选择合适的压缩选项？ A: 不同格式有不同的压缩策略：

• JPEG:

  • quality: 75-85 是平衡质量和体积的最佳范围
  • progressive: 适合网络传输，可渐进加载
  • mozjpeg: 使用 mozjpeg 编码器可获得更好的压缩率

• PNG:

  • compressionLevel: 9 是最大压缩，但处理时间较长
  • palette: 对简单图形（如 logo、图标）启用调色板可大幅减小体积
  • effort: 7 是默认值，可根据需要调整（1-10）

• WebP:

  • quality: 80-90 通常能获得很好的压缩效果
  • lossless: 对需要保持透明度的图片可考虑无损模式
  • effort: 4 是默认值，数值越大压缩时间越长但效果更好