# TinyPNG-Scripts

**Repository Path**: xiaofeiwuu/tiny-png-scripts

## Basic Information

- **Project Name**: TinyPNG-Scripts
- **Description**: TinyPNG 批量压缩脚本
🚀 双模式图片批量压缩工具，支持官方 API 和免费爬虫两种模式。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-31
- **Last Updated**: 2025-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TinyPNG 批量压缩脚本

🚀 **双模式图片批量压缩工具**，支持官方 API 和免费爬虫两种模式。

## ✨ 功能特性

### 🔑 双压缩模式
- **API 版本** (`api.js`)：使用 TinyPNG 官方 API，稳定可靠，支持多 API key 自动切换
- **爬虫版本** (`crawler.js`)：使用网页接口，完全免费，无需 API key

### 🎯 智能特性
- 🧠 **自动模式选择**：未配置 API key 时自动使用爬虫模式
- 🔄 **智能切换**：API 配额用完时可自动切换到爬虫模式
- 📊 **详细统计**：显示压缩结果和节省的空间
- 💎 **多 Key 支持**：API 版本支持多个 key 自动轮换

### 🛠️ 便捷功能
- 📁 递归扫描目录下所有图片
- 🎯 支持 JPG、JPEG、PNG、WebP 格式
- 💾 可选择替换原文件或输出到新目录
- 🗂️ 保持原有目录结构
- ⚠️ 失败文件自动保存，支持重试

## 🚀 快速开始

### 1. 安装依赖
```bash
npm install
```

### 2. 配置（API 版本需要）
```bash
# 复制配置文件
cp .env.example .env

# 编辑配置文件，添加你的 API key
# 访问 https://tinypng.com/developers 获取免费 API key
```

### 3. 使用方法

#### API 版本（推荐）
```bash
# 压缩图片
npm run api

# 重试失败文件
npm run api:retry

# 直接运行
node api.js
node api.js --retry-failed
```

#### 爬虫版本（完全免费）
```bash
# 压缩图片
npm run crawler

# 重试失败文件  
npm run crawler:retry

# 直接运行
node crawler.js
node crawler.js --retry-failed
```

## ⚙️ 配置选项

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `TINYPNG_API_KEY` | - | API keys，支持多个（逗号分隔） |
| `SOURCE_ROOT` | `./static` | 源图片目录 |
| `REPLACE_ORIGINAL` | `false` | 是否直接替换原文件 |
| `OUTPUT_ROOT` | `./compressed` | 输出目录（非替换模式） |
| `FAILED_DIR` | `./failed_images` | 失败文件目录 |
| `FILE_DELAY` | `200` | 文件间处理延迟（毫秒） |
| `LOG_LEVEL` | `normal` | 日志级别（minimal/normal/verbose） |

## 🔑 多 API Key 配置

```bash
# .env 文件中配置多个 key
TINYPNG_API_KEY=key1_xxxxxxxx,key2_yyyyyyyy,key3_zzzzzzzz
```

**自动切换机制**：
- 当前 key 达到月度限制（500张）时自动切换
- 显示每个 key 的使用情况
- 最大化免费配额利用

## 🆚 版本对比

| 特性 | API 版本 | 爬虫版本 |
|------|----------|----------|
| **费用** | 需要 API key，免费 500张/月 | 完全免费 |
| **稳定性** | 高，官方接口 | 中，依赖网页接口 |
| **速度** | 快 | 相对较慢 |
| **多 Key 支持** | ✅ | ❌ |
| **使用限制** | 500张/月/key | 无官方限制 |
| **推荐场景** | 生产环境，大量图片 | 测试，偶尔使用 |

## 📖 使用示例

### 基本使用
```bash
# 1. 将图片放入 static 目录
# 2. 运行压缩
npm run crawler  # 免费版本，无需配置

# 3. 查看结果
# 压缩后的图片在 compressed 目录
# 失败的图片在 failed_images 目录
```

### 替换原文件模式
```bash
# 在 .env 中设置
REPLACE_ORIGINAL=true

# 运行压缩（会直接替换原文件）
npm run api
```

### 重试失败文件
```bash
# 重试失败的文件
npm run api:retry
npm run crawler:retry
```

## 🐛 常见问题

### API 版本问题
- **API key 无效**：检查 key 是否正确，是否超过月度限制
- **网络错误**：检查网络连接，增加 FILE_DELAY

### 爬虫版本问题  
- **压缩失败**：网络问题或临时限制，稍后重试
- **速度较慢**：正常现象，免费版本相对较慢

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**让图片压缩变得简单高效！** 🎉