pixcraft 0.1.0

本地批量图片处理 CLI 工具——压缩、转格式、改尺寸、去信息，一行命令搞定

PixCraft

批量处理图片的命令行工具。压缩、转格式、改尺寸、清除元数据，一条命令的事。

写这个工具的原因很简单——每次要批量压缩图片就得打开 TinyPNG 网页，或者翻出 Photoshop 脚本，太烦了。PixCraft 把这些操作全部搬到了终端里。

---

安装

Python 3.10 以上，依赖 Click 和 Pillow，pip 会自动装好。

pip install pixcraft

也可以从源码装：

git clone https://github.com/your-org/pixcraft.git
cd pixcraft
pip install .

---

快速开始

五个命令，覆盖最常见的图片处理需求：

# 批量压缩到 500KB 以内
pixcraft compress ./images/ -s 500k

# 整个目录转 WebP
pixcraft convert ./images/ -t webp

# 等比缩放到 1200 宽
pixcraft resize hero.jpg -w 1200

# 清除 EXIF/GPS/相机信息
pixcraft strip ./photos/

# 查看图片详情
pixcraft info photo.jpg

---

命令详解

pixcraft compress

压缩图片。可以指定质量，也可以指定目标文件大小让工具自己找最佳参数。

pixcraft compress <PATH> [OPTIONS]

选项	类型	默认值	说明
-q, --quality	int	85	压缩质量 1-100，越大质量越好，文件也越大
-s, --max-size	str	—	目标文件大小上限，比如 500k、5mb。指定后自动二分搜索找最佳质量值
-o, --output	path	./pixcraft-output	输出目录
-f, --format	str	—	输出格式（jpg/png/webp/avif），不指定就用原格式
--no-resize	flag	false	禁止自动缩小尺寸，只靠降低质量来压缩

几个默认行为值得注意：

• PATH 可以是单个文件或目录，目录会递归处理
• 默认把图片最长边缩到 2000px，防止超大尺寸撑爆文件体积
• 指定 --max-size 时用二分搜索找质量值，比你自己试快得多
• 质量降到最低还是超的话，会自动逐级缩小尺寸（2000px → 1000px → 500px）

pixcraft convert

JPG、PNG、WebP、AVIF 四种格式互转。

pixcraft convert <PATH> -t <TARGET_FORMAT> [OPTIONS]

选项	类型	默认值	说明
-t, --to	str	必填	目标格式（jpg/png/webp/avif）
-q, --quality	int	85	输出质量，只对 jpg/webp/avif 生效
-o, --output	path	./pixcraft-output	输出目录
--lossless	flag	false	无损模式，目前只支持 PNG → WebP

转换时会做一些自动处理，防止出问题：

• PNG → JPG 会自动填白色背景（透明区域没法往 JPG 里塞）
• JPG → PNG 直接拒绝，JPG 已经有损了，转 PNG 只是浪费空间
• PNG → WebP 加 --lossless 能保留透明通道
• 其他方向正常转

pixcraft resize

四种缩放模式，比 ImageMagick 的参数好记多了。

pixcraft resize <PATH> [OPTIONS]

选项	类型	默认值	说明
-w, --width	int	—	目标宽度，高度自动按比例算
-h, --height	int	—	目标高度，宽度自动按比例算
--fit	str	—	适配尺寸如 1200x630，图片完整显示，空白处填白
--fill	str	—	填充尺寸如 1200x630，铺满区域，超出居中裁剪
--scale	float	—	缩放倍数，0.5 就是缩小一半
-o, --output	path	./pixcraft-output	输出目录

四种模式：

• -w / -h：等比缩放。只给一个边就自动算另一边，两个都给就按固定尺寸来
• --fit：把图片塞进指定区域，保持比例，留白不裁剪
• --fill：填满指定区域，保持比例，多出来的裁掉
• --scale：直接按倍数缩放，最简单直接

pixcraft strip

清除元数据，保护隐私。去掉 EXIF、GPS 坐标、相机型号、拍摄时间。

pixcraft strip <PATH> [OPTIONS]

选项	类型	默认值	说明
-o, --output	path	—	输出目录，不指定就覆盖原文件

在社交媒体发照片之前跑一下这个命令，就不用担心别人从 EXIF 里读到你家的 GPS 坐标了。

pixcraft info

查看图片的详细信息。

pixcraft info <PATH>

只接受单个文件，不支持目录。

会输出这些内容：文件名、格式、尺寸、文件大小、颜色模式，还有 EXIF 里藏的各种信息（相机型号、拍摄时间、GPS 等）。

---

输出示例

批量处理时会逐文件显示状态和体积变化：

  ✓ hero.jpg (4.2MB -> 0.3MB)
  ✓ photo.png (2.1MB -> 0.5MB)
  ✓ banner.webp (1.8MB -> 0.4MB)
  ✗ broken.jpg (无法读取，已跳过)

  处理完成：3/4 个文件，节省 6.9MB

成功打勾，失败打叉并附原因，最后汇总成功数和节省的总体积。

---

测试

89 passed in 4.24s

---

开源协议

MIT License

---

PixCraft —— 给开发者用的命令行版 TinyPNG。