# Image compression tool

**Repository Path**: harry_shen/image-compression-tool

## Basic Information

- **Project Name**: Image compression tool
- **Description**: 图片批量压缩工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🖼️ 图片批量压缩工具使用文档

## 🚀 快速开始

### 基本用法

```bash
go run . -input ./images -output ./compressed
```

---

## 📋 参数说明

### 📁 基础路径参数

| 参数 | 默认值 | 说明 | 示例 |
|------|--------|------|------|
| `-input` | `./images` | **输入图片目录**（支持相对/绝对路径） | `-input /home/user/photos` |
| `-output` | `./compressed` | **输出目录**（自动创建） | `-output ./optimized_images` |

---

### 🎨 图片质量参数

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `-quality` | `80` | `1-100` | **JPEG/WebP 压缩质量** |

#### Quality 详细说明：

| 质量值 | 效果 | 适用场景 |
|--------|------|---------|
| `1-30` | 极低质量，文件极小 | 缩略图、预览图 |
| `40-60` | 中等质量，明显压缩痕迹 | 网页正文图片 |
| `70-80` | ⭐ **推荐**，质量与体积平衡 | 网站图片、社交媒体 |
| `85-95` | 高质量，肉眼难辨差异 | 产品展示、相册存储 |
| `96-100` | 接近无损，文件较大 | 印刷品质、专业存档 |

```bash
# 高质量压缩（推荐用于照片）
go run . -quality 85

# 极致压缩（适合网页）
go run . -quality 60
```

---

### 📐 尺寸调整参数

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `-width` | `460` | `0-10000+` | **最大宽度**（像素），`0` = 不限制 |
| `-height` | `0` | `0-10000+` | **最大高度**（像素），`0` = 自适应（等比例计算） |

#### 使用示例：

```bash
# 固定宽度460px，高度自适应（默认配置）
go run .

# 限制为 1920x1080 以内（保持比例）
go run . -width 1920 -height 1080

# 仅限制高度为800px，宽度自适应
go run . -width 0 -height 800

# 不改变尺寸（仅压缩质量）
go run . -width 0 -height 0
```

#### 尺寸限制行为说明：

| 设置 | 输入图片 | 输出结果 | 说明 |
|------|---------|---------|------|
| `-w 800 -h 0` | 4000×3000 | **800×600** | 宽度优先，高度按比例缩小 |
| `-w 0 -h 800` | 3000×4000 | **600×800** | 高度优先，宽度按比例缩小 |
| `-w 1920 -h 1080` | 3000×2000 | **1620×1080** | 双向限制，取较小缩放比 |
| `-w 1920 -h 1080` | 800×600 | **800×600** | 已满足条件，不放大 |

---

### 🔧 缩放模式 (`-mode`)

| 模式 | 说明 | 示意图 | 适用场景 |
|------|------|--------|---------|
| `fit` | ⭐ **默认**，等比例缩放适应容器（可能留白） | 见下方 | 保持原图比例的缩略图 |
| `fill` | 等比例缩放后**居中裁剪**填满容器 | 见下方 | 头像、封面图、固定尺寸展示 |
| `resize` | 强制拉伸到指定尺寸（可能变形） | 见下方 | 背景纹理、无需保持比例时 |

```
Fit 模式 (fit):          Fill 模式 (fill):        Resize 模式 (resize):
┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│              │         │ ┌──────────┐ │         │              │
│   ┌────┐     │         │ │  原图内容  │ │         │   ┌────────┐  │
│   │    │     │         │ │  (裁剪)   │ │         │   │  拉伸变形│  │
│   └────┘     │         │ └──────────┘ │         │   └────────┘  │
│              │         │              │         │              │
└──────────────┘         └──────────────┘         └──────────────┘
 保持比例，可能留白       保持比例，裁剪填满         强制变形
```

```bash
# 生成正方形头像（填充并裁剪）
go run . -mode fill -width 200 -height 200

# 生成响应式图片（适应容器）
go run . -mode fit -width 1920 -height 1080
```

---

### 🎭 重采样滤波器 (`-filter`)

| 滤波器 | 质量 | 速度 | 说明 |
|--------|------|------|------|
| `lanczos` | ⭐⭐⭐ 最高 | 最慢 | 适合高质量照片缩放（推荐） |
| `catmullrom` | ⭐⭐⭐ 高 | 较快 | 锐利边缘，类似Lanczos但更快 |
| `mitchellnetravali` | ⭐⭐ 高 | 中等 | 平滑结果，减少振铃效应 |
| `linear` | ⭐⭐ 中等 | 快 | 双线性插值，平衡之选 |
| `box` | ⭐ 一般 | 很快 | 平均采样，适合大幅缩小 |
| `nearestneighbor` | ⭐ 最低 | 最快 | 最近邻，无抗锯齿（像素风） |

```bash
# 最高质量（推荐用于照片）
go run . -filter lanczos

# 快速处理大量图片
go run . -filter linear

# 像素风格游戏素材
go run . -filter nearestneighbor
```

---

### ⚡ 性能参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-workers` | CPU核心数 | **并发处理线程数** |

```bash
# 使用8个线程并行处理
go run . -workers 8

# 单线程处理（调试时使用）
go run . -workers 1
```

> 💡 **提示**: 设为CPU核心数的1-2倍可获得最佳性能，过高可能导致内存压力。

---

## 🎨 高级特效参数

### 🔄 自动方向校正

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-auto-orient` | `true` | 根据 **EXIF 信息**自动旋转图片 |

```bash
# 手机拍照通常是横向录制，需要此功能
go run . -auto-orient

# 禁用自动旋转
go run . -auto-orient=false
```

> ⚠️ **重要**: 手机拍摄的照片通常包含EXIF方向信息，建议保持开启！

---

### 🌈 灰度转换

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-grayscale` | `false` | 将图片转换为**黑白/灰度图** |

```bash
# 批量转换为黑白照片
go run . -grayscale
```

---

### 🌫️ 高斯模糊

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `-blur` | `0` | `0-20+` | **高斯模糊半径**（`0`=禁用） |

```bash
// 轻微模糊（背景虚化效果）
go run . -blur 2.5

// 强烈模糊（隐私保护）
go run . -blur 10
```

---

### 💡 亮度调整

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `-brightness` | `0` | `-100 ~ +100` | **亮度调整** |

```bash
// 提亮图片 (+50%)
go run . -brightness 50

// 变暗图片 (-30%)
go run . -brightness -30
```

---

### ○ 对比度调整

| 参数 | 默认值 | 范围 | 说明 |
|------|--------|------|------|
| `-contrast` | `0` | `-100 ~ +100` | **对比度调整** |

```bash
// 增强对比度（电影感）
go run . -contrast 25

// 降低对比度（柔和效果）
go run . -contrast -20
```

---

### 💧 水印文字

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-watermark` | `` (空) | **水印文字**（留空则不添加） |

```bash
// 添加版权水印
go run . -watermark "© 2024 MyCompany"

// 添加日期水印
go run . -watermark "2024-01-15"
```

> 📍 水印位置：右下角，半透明黑色背景 + 白色文字

---

## 📖 完整使用示例

### 场景1：网站图片优化

```bash
go run . \
  -input ./original_photos \
  -output ./web_optimized \
  -quality 75 \
  -width 1920 \
  -mode fit \
  -filter lanczos \
  -workers 8
```

### 场景2：社交媒体批量处理

```bash
go run . \
  -input ./raw_photos \
  -output ./social_media \
  -quality 85 \
  -width 1080 \
  -height 1080 \
  -mode fill \
  -auto-orient
```

### 场景3：生成产品缩略图

```bash
go run . \
  -input ./products \
  -output ./thumbnails \
  -quality 90 \
  -width 300 \
  -height 300 \
  -mode fill \
  -filter box
```

### 场景4：艺术效果处理

```bash
go run . \
  -input ./photos \
  -output ./artistic \
  -grayscale \
  -contrast 30 \
  -brightness -10 \
  -blur 1.5 \
  -watermark "Photography by AI"
```

### 场景5：快速预览图生成

```bash
go run . \
  -input ./high_res \
  -output ./previews \
  -quality 50 \
  -width 400 \
  -filter linear \
  -workers 16
```

### 场景6：仅压缩不改变尺寸

```bash
go run . \
  -input ./archive \
  -output ./compressed_archive \
  -quality 85 \
  -width 0 \
  -height 0
```

---

## 🔧 查看帮助信息

```bash
go run . -h
```

或

```bash
go run . --help
```

---

## ⌨️ 参数速查表

| 简写 | 完整参数 | 类型 | 默认值 | 说明 |
|------|---------|------|--------|------|
| | `-input` | string | `./images` | 输入目录 |
| | `-output` | string | `./compressed` | 输出目录 |
| | `-quality` | int | `80` | 压缩质量 (1-100) |
| | `-width` | int | `460` | 最大宽度 (0=不限) |
| | `-height` | int | `0` | 最大高度 (0=自适应) |
| | `-mode` | string | `fit` | fit/fill/resize |
| | `-filter` | string | `lanczos` | 重采样算法 |
| | `-workers` | int | CPU数 | 并发线程数 |
| | `-auto-orient` | bool | `true` | EXIF方向校正 |
| | `-grayscale` | bool | `false` | 灰度转换 |
| | `-blur` | float64 | `0` | 模糊半径 |
| | `-brightness` | float64 | `0` | 亮度 (-100~100) |
| | `-contrast` | float64 | `0` | 对比度 (-100~100) |
| | `-watermark` | string | `` | 水印文字 |

---

## 📝 注意事项

1. **输出目录会保留输入目录的子结构**
2. **PNG 格式不支持 quality 参数**（PNG 是无损压缩）
3. **处理大图片时建议适当降低 `-workers`** 避免内存不足
4. **`-auto-orient` 对手机拍摄的照片非常重要**
5. **质量参数仅对 JPEG/WebP 生效**