# thumbkit

**Repository Path**: reginx/thumbkit

## Basic Information

- **Project Name**: thumbkit
- **Description**: 跨平台图片缩略图批量处理工具。递归遍历目录，基于宽度 + 文件大小双维度智能判断，自动缩放或压缩图片。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# thumbkit

跨平台图片缩略图批量处理工具。递归遍历目录，基于**宽度 + 文件大小**双维度智能判断，自动缩放或压缩图片。

## 特性

- **双维度智能判断**：宽度超限 → 等比缩放；文件大小超限 → 降低质量压缩；都不超 → 跳过
- **文件头格式检测**：通过魔术字节检测真实图片格式，而非依赖扩展名，避免解码失败
- **双模式输出**：指定 `-out` 输出到目标目录（保持目录结构），或原地覆盖原图
- **原子安全写入**：原地模式使用临时文件 + `rename`，进程崩溃不损坏原图
- **Worker Pool 并发**：默认 CPU 核数并发处理，可自定义
- **实时进度**：每秒刷新进度条，显示处理速率
- **汇总统计**：完成后输出总耗时、缩放/压缩数量、空间节省比例
- **跨平台**：纯 Go 实现，零 CGO 依赖，Windows / macOS / Linux 均可编译运行
- 支持格式：JPEG、PNG、GIF、WebP、BMP、TIFF

## 安装

```bash
go install github.com/reginx/thumbkit@latest
```

## 编译

```bash
# 当前平台
make build

# 交叉编译全平台（输出到 bin/）
make build-all

# 仅 Windows
make build-win

# 或手动编译
go build -o thumbkit .
GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o thumbkit.exe .
```

## 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-src` | string | (必选) | 源图片目录路径 |
| `-out` | string | "" | 输出目录（空 = 原地覆盖原图） |
| `-width` | int | 800 | 最大宽度 px，等比缩放 |
| `-quality` | int | 85 | JPEG 质量 1-100 |
| `-maxsize` | string | "" | 最大文件大小，如 `500KB`、`1.5MB`（空 = 不限制） |
| `-recursive` | bool | true | 是否递归遍历子目录 |
| `-workers` | int | CPU 核数 | 并发 Worker 数量 |
| `-overwrite` | bool | false | out 模式下是否覆盖已存在的文件 |

## 处理逻辑

### 双维度判断

| 宽度 ≤ max | 大小 ≤ maxsize | 行为 |
|:---:|:---:|------|
| ✅ | ✅ | 跳过（原地）/ 复制（out） |
| ❌ | ✅ | 等比缩放 |
| ✅ | ❌ | 仅压缩（保持尺寸，降低质量重编码） |
| ❌ | ❌ | 缩放 + 压缩 |

### 格式处理

- **解码**：通过读取文件头魔术字节检测真实格式，不依赖扩展名，避免 `.png` 实际是 JPEG 等情况导致解码失败
- **原地编码**：以源文件扩展名决定输出编码格式，保证文件名不变且内容格式与扩展名一致
- **out 编码**：以检测到的真实格式作为输出编码格式

## 使用示例

```bash
# 输出到指定目录（保持子目录结构）
thumbkit -src ./photos -width 1200 -quality 80 -out ./thumbs

# 原地处理：宽度超 1024px 或体积超 500KB 的图片
thumbkit -src ./photos -width 1024 -maxsize 500KB -quality 75

# 仅限制文件大小，不限宽度
thumbkit -src ./photos -maxsize 1MB -quality 80

# 非递归，高并发
thumbkit -src ./photos -recursive=false -workers 16 -out ./thumbs

# 指定输出目录，覆盖已有文件
thumbkit -src ./photos -width 800 -out ./thumbs -overwrite
```

## 输出格式

| 源格式 | 输出格式 | 备注 |
|--------|----------|------|
| JPEG | JPEG | 支持 `-quality` 调节质量 |
| PNG | PNG | 无损重编码 |
| GIF | PNG | 取第一帧 |
| WebP | PNG | - |
| BMP | PNG | - |
| TIFF | PNG | - |

## 项目结构

```
thumb/
├── main.go                       # 程序入口
├── Makefile                      # 编译脚本
├── go.mod / go.sum               # 依赖管理
└── internal/
    ├── config/config.go          # 命令行参数解析
    ├── walker/walker.go          # 递归目录遍历 + 图片过滤
    ├── processor/processor.go    # 图片处理核心：格式检测、解码、缩放、编码、原子写入
    ├── processor/pool.go         # Worker Pool 并发调度
    └── reporter/reporter.go      # 进度统计 + 汇总报告
```

## License

MIT