0.1.0 • Published yesterdayCLI

@yxw007/cimg-cli

Licence

MIT

Version

0.1.0

Deps

Size

20 kB

Vulns

Weekly

Stars

Summary Dependency Versions

cimg-cli

一款轻量、高效的图片压缩 CLI 工具，支持 PNG、JPG/JPEG、GIF 格式的批量压缩与单文件压缩。

GitHub top language GitHub License NPM Version GitHub Actions Workflow Status

特性

支持 PNG / JPG / JPEG / GIF 四种常见图片格式
文件夹批量压缩 — 自动递归扫描目录下所有支持的图片
单文件压缩 — 指定单个图片文件即可压缩
可调压缩质量 — 通过 -q / --quality 参数控制（0–100）
自定义输出路径 — 通过 -o / --output 指定输出目录或文件名
保持目录结构 — 文件夹模式下保持原始子目录结构
防覆盖保护 — 默认跳过已存在的输出文件，--force 可强制覆盖
压缩统计 — 显示压缩前后大小对比与节省比例
基于 sharp — 使用高性能 sharp 库进行图片处理
可扩展架构 — 基于接口设计，易于扩展支持更多图片格式

安装

npm install -g @yxw007/cimg-cli

或者使用 npx：

npx cimg-cli <input> [options]

快速开始

压缩单张图片

# 使用默认质量（80），输出为 .min.{ext}
cimg ./images/photo.png

# 指定压缩质量为 30
cimg ./images/photo.png -q 30

# 指定输出文件路径
cimg ./images/photo.png -o ./compressed/photo.png

压缩文件夹

# 压缩文件夹下所有图片，默认输出到 ./output/ 目录
cimg ./images

# 指定输出目录
cimg ./images -o ./build

# 指定压缩质量
cimg ./images -q 30 -o ./build

使用指南

命令行参数

参数	全称	描述	默认值
`<input>`	—	输入文件或文件夹路径	必填
`-o <path>`	`--output <path>`	输出文件或目录路径	见下方说明
`-q <number>`	`--quality <number>`	压缩质量 (0–100)	`80`
`--force`	—	覆盖已存在的输出文件	`false`
`-V`	`--version`	查看版本号	—
`-h`	`--help`	查看帮助信息	—

输出路径规则

单文件模式

未指定 -o：在原目录生成 {文件名}.min.{扩展名}
- 例：cimg /path/to/photo.png → /path/to/photo.min.png
指定 -o：使用指定的完整路径作为输出
- 例：cimg /path/to/photo.png -o /path/to/compressed.png → /path/to/compressed.png

文件夹模式

未指定 -o：输出到当前工作目录下的 output/ 目录，文件加 .min 后缀，保持原始相对路径
```
输入目录：
/d/xx/a.png
/d/xx/yy/b.jpg

压缩后：
./output/a.min.png
./output/yy/b.min.jpg
```

指定 -o：输出到指定目录，保持原名和相对路径

cimg /d/xx -o ./build

压缩后：
./build/a.png
./build/yy/b.jpg

示例

# 压缩单文件并指定质量
cimg ./images/banner.png -q 50

# 文件夹压缩到指定目录
cimg ./images -o ./build -q 30

# 强制覆盖已存在的输出文件
cimg ./images -o ./build --force

# 查看帮助
cimg --help

输出示例

单文件压缩

🖼️  Processing file: photo.png
  ✅ photo.min.png
  📊 1.2 MB → 0.4 MB (66.7% saved)

文件夹压缩

📁 Processing folder: ./images
  ✅ images/banner.png → output/banner.min.png (2.1 MB → 0.3 MB, 85.7% saved)
  ✅ images/photo.jpg → output/photo.min.jpg (1.5 MB → 0.6 MB, 60.0% saved)
  ✅ images/sub/icon.gif → output/sub/icon.min.gif (0.8 MB → 0.5 MB, 37.5% saved)

📊 Summary: 3 compressed, 0 skipped/failed
   Total: 4.4 MB → 1.4 MB (68.2% saved)

支持的格式

格式	扩展名	压缩方式
PNG	`.png`	sharp png (quality)
JPG / JPEG	`.jpg`, `.jpeg`	sharp jpeg (quality, mozjpeg)
GIF	`.gif`	sharp gif (animated)

开发

技术栈

TypeScript — 类型安全
sharp — 高性能图片处理
commander — CLI 框架
Rolldown — 打包构建
Vitest — 单元测试

克隆与开发

# 克隆仓库
git clone https://github.com/yxw007/cimg-cli.git
cd cimg-cli

# 安装依赖
npm install

# 开发模式（监听文件变化自动构建）
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 本地测试 CLI
node bin/cimg.js ./test.png -q 80

项目结构

cimg-cli/
├── bin/
│   └── cimg.js            # CLI 入口
├── src/
│   ├── index.ts            # 主入口（commander 配置）
│   ├── types.ts            # 类型定义
│   ├── core/
│   │   ├── compressor.interface.ts  # 压缩器接口
│   │   └── processor.ts             # 压缩处理逻辑
│   ├── compressors/
│   │   ├── index.ts                 # 压缩器注册表
│   │   ├── png.compressor.ts        # PNG 压缩器
│   │   ├── jpg.compressor.ts        # JPG 压缩器
│   │   └── gif.compressor.ts        # GIF 压缩器
│   └── utils/
│       ├── path.ts         # 路径工具函数
│       └── file.ts         # 文件工具函数
├── tests/                  # 单元测试
├── rolldown.config.mts     # Rolldown 构建配置
├── tsconfig.json           # TypeScript 配置
├── vitest.config.ts        # Vitest 测试配置
└── package.json

扩展新图片格式

cimg-cli 采用接口化设计，新增图片格式只需实现 ICompressor 接口并注册即可：

import type { ICompressor } from "../core/compressor.interface.js";
import type { CompressOptions, CompressResult } from "../types.js";

export class WebpCompressor implements ICompressor {
  readonly supportedExtensions = [".webp"];

  async compress(inputPath: string, outputPath: string, options: CompressOptions): Promise<CompressResult> {
    // 实现压缩逻辑
  }
}

然后在 src/compressors/index.ts 中注册：

registry.register(new WebpCompressor());

许可证

MIT yxw007

Keywords

image compression cli png jpg gif