change-image-suffix

🖼️ 批量转换图片格式的 CLI 工具，支持递归搜索、深度限制、Windows 右键菜单等功能。

功能特性

• 📁 支持指定目录或使用当前目录
• 🔄 支持递归搜索子目录
• 📏 支持递归深度限制
• 🎯 支持指定源文件后缀（png, jpg, gif 等）
• 🎨 支持多种目标格式（webp, jpg, png, avif, tiff）
• 📤 输出到 <目标格式>/ 子目录（如 webp/, jpg/）
• 🔢 同名不同后缀文件自动编号（_01, _02）
• 🖱️ Windows 右键菜单集成
• ⚡ 基于 sharp 高性能图片处理

快速开始

# 安装
npm install -g change-image-suffix

# 基本用法（转换当前目录图片为 webp）
cis

# 指定目录
cis -p ./images

# 递归转换
cis -r

常用命令

| 场景 | 命令 | |------|------| | 转换当前目录 → webp | cis | | 转换指定目录 → webp | cis -p ./photos | | 递归转换所有子目录 | cis -r | | 递归，限制深度 2 层 | cis -r -d 2 | | 仅转换 png 和 jpg | cis -e png,jpg | | 转换为 jpg 格式 | cis -t jpg | | 转换为 avif（更小体积） | cis -t avif | | 单个文件转换 | cis -f ./banner.png | | 多文件批量转换 | cis -f ./a.png ./b.jpg ./c.gif | | 多选文件/目录混合 | cis file1.png dir1 file2.jpg | | 显示帮助 | cis --help |

Windows 右键菜单

# 注册右键菜单（只需执行一次）
cis install-menu

# 卸载右键菜单
cis uninstall-menu

注册后，在文件夹或图片文件上右键 → 悬停即可看到格式子菜单：

🖼 转换图片 (cis)    ← 悬停展开
  ├── 🌀 WebP       ← 默认
  ├── 📷 JPG
  ├── 🖼 PNG
  ├── 📺 AVIF
  └── 📋 TIFF

适用场景：

• 📁 文件夹空白处右键 → 转换该目录所有图片
• 📁 文件夹图标上右键 → 转换该目录所有图片
• 🖼 图片文件上右键 → 转换该单个图片
• 🔢 支持多选文件/文件夹后右键
• 🔀 支持文件和目录混合选择 → 自动识别并处理所有图片

注意：

• 非图片文件右键显示菜单但不会处理（静默跳过）
• 混合选择时会获取所有选中项中的图片文件进行转换

命令行参数

| 参数 | 说明 | 默认值 | |------|------|--------| | -p, --path <dir> | 指定工作目录 | 当前目录 | | -r, --recursive | 递归搜索子目录 | 否 | | -d, --depth <n> | 递归深度限制 | 无限制 | | -e, --extensions | 指定源后缀，逗号分隔 | png,jpg,jpeg,gif,bmp,tiff,tif,webp,avif | | -t, --to <format> | 目标格式 | webp | | -f, --file <file> | 指定单个文件转换 | - | | -h, --help | 显示帮助 | - | | -v, --version | 显示版本 | - |

文件命名规范

转换后的文件输出到 <目标格式>/ 子目录下（例如转换为 webp 则输出到 webp/，转换为 jpg 则输出到 jpg/），命名规则如下：

同名不同后缀 → 自动编号

当源目录中存在同名但不同扩展名的文件时，按字母顺序编号：

源目录:  photo.png + photo.jpg + photo.gif
输出:    webp/photo_01.webp
        webp/photo_02.webp
        webp/photo_03.webp

不同名或不同文件 → 直接覆盖

源目录:  banner.png + logo.jpg
输出:    webp/banner.webp
        webp/logo.webp

同格式转换 → 直接覆盖

源目录:  photo.webp
输出:    webp/photo.webp  (直接复制，无双重后缀)

输出目录结构

📁 原目录/
├── 📁 webp/             ← 转换后的 webp 文件
│   ├── photo.webp
│   ├── banner.webp
│   └── photo_01.webp
├── 📁 jpg/              ← 转换后的 jpg 文件
│   └── ...
├── photo.png
├── banner.jpg
└── logo.gif

支持的格式

| 类型 | 格式 | |------|------| | 输入 | png, jpg, jpeg, gif, bmp, tiff, webp, avif | | 输出 | webp, jpg, png, avif, tiff |

使用示例

示例 1：批量转换照片集

# 将 photos 目录下的所有图片递归转换为 webp
cis -r -p ./photos -t webp

示例 2：压缩图片体积

# 将图片转换为 avif（体积更小，画质接近）
cis -p ./screenshots -t avif

示例 3：仅处理 PNG 图片

# 只转换 png 格式，输出为 jpg
cis -p ./icons -e png -t jpg

示例 4：限制递归深度

# 只递归 1 层子目录
cis -r -d 1 -p ./project

示例 5：单文件转换

# 转换单个文件，指定输出格式
cis -f ./avatar.png -t webp

示例 6：多选文件/目录批量转换

# 多选文件（空格分隔），每个文件的输出在其所在目录的 <目标格式>/
cis ./photo1.png ./photo2.jpg ./folder3

# 多选多个目录
cis ./images ./icons ./logos

💡 多选时：每个文件/目录的输出结果放在各自所在目录的 <目标格式>/ 子目录中（如 webp/, jpg/），互不干扰。

安装与更新

# 安装
npm install -g change-image-suffix

# 更新
npm update -g change-image-suffix

开发

# 克隆项目
git clone https://github.com/GuoSirius/change-image-suffix.git
cd change-image-suffix

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 链接到全局（开发时）
npm link

提交规范

项目使用 Conventional Commits 规范，提交信息格式：

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

type 类型：

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式（不影响代码运行的变动）
• refactor: 重构
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具类改动

发布流程

# 执行一键发布脚本
npm run release

# 或指定版本类型
npm run release:patch   # 修复bug
npm run release:minor   # 新增功能  
npm run release:major   # 重大变更

发布脚本会自动：

1. 检测未提交文件并提示提交
2. 交互式选择版本更新类型
3. 更新版本号和 CHANGELOG.md
4. 推送至远程仓库
5. 发布到 npm

项目结构

├── .claude/              # Claude Code 项目记忆与设置
│   ├── MEMORY.md
│   ├── memory/
│   └── settings.local.json
├── .github/workflows/   # GitHub Actions 工作流
│   └── release.yml      # 自动发布工作流
├── .husky/              # Git 钩子
│   └── commit-msg       # 提交信息校验钩子
├── scripts/             # 脚本目录
│   ├── release.js       # 一键发布脚本
│   ├── postinstall.js   # npm postinstall 钩子（自动注册右键菜单）
│   └── preuninstall.js  # npm preuninstall 钩子（自动清理右键菜单）
├── src/                 # 源代码
│   └── index.ts         # 主入口
├── CLAUDE.md            # 项目上下文文档
├── .commitlintrc.json   # commitlint 配置
├── CHANGELOG.md         # 变更日志
└── package.json         # 项目配置

License

MIT