@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 | 静默模式，仅输出错误信息 | | --help | -h | 显示帮助信息 |

示例

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

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

Vite 插件

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

配置

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

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

export default defineConfig({
  plugins: [
    compressVitePlugin({
      // 1. 覆盖通用质量
      quality: 75,

      // 2. 覆盖 PNG 特定选项 (注意：如果覆盖对象，需要提供完整属性，或者插件逻辑里做深度合并)
      // 根据当前代码实现是浅合并，所以如果只写 palette，compressionLevel 可能会丢失(如果默认值是在loader里处理的)
      // 实际上 loader.js 做了深度合并，但 vite 插件里的 options 是顶层覆盖。
      // 建议：如果只改一项，尽量在 compress.config.js 里改。
      // 如果必须在这里改，传入完整对象：
      pngOptions: {
        compressionLevel: 6,
        palette: false,
      },

      // 3. 甚至可以开启尺寸限制（虽然通常不建议在构建时改变原图尺寸）
      resize: {
        maxWidth: 1024,
      },

      // 4. 控制缓存
      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/WebP)
  // 范围 1-100，默认 88
  quality: 88,

  // PNG 专属配置
  pngOptions: {
    compressionLevel: 9, // 压缩等级 0-9，默认 9
    palette: true, // 是否启用调色板量化，默认 true (显著减小体积)
  },

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

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

  // [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），源代码保持不变。