201 lines
5.0 KiB
Markdown
201 lines
5.0 KiB
Markdown
# TinyPNG 批量压缩工具
|
||
|
||
这是一个基于 Tinify/TinyPNG Python SDK 的批量图片压缩和格式转换工具。支持 GUI 界面、多个 API Key 按顺序接力使用、官方额度同步、批量转换格式，以及递归处理目录。
|
||
|
||
## 功能
|
||
|
||
- 图形界面选择输入目录和输出目录。
|
||
- 支持多个 Tinify API Key，每个 Key 默认每月 500 张额度，处理时会先用完前一个 Key，再切换到下一个。
|
||
- 启动处理前可同步官方本月已用额度。
|
||
- 支持 PNG、JPG/JPEG、WebP、AVIF 图片。
|
||
- 支持转换为 png、jpeg、webp、avif，也支持“全部格式”一次输出四种格式。
|
||
- 支持递归扫描目录。
|
||
- 支持覆盖已有输出文件或跳过已有文件。
|
||
- 支持试运行，只预览计划，不调用 Tinify API。
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
C:\dev\py\tinypng
|
||
├─ source\ 默认输入目录，把待处理图片放这里
|
||
├─ optimized\ 默认输出目录，运行后自动生成
|
||
├─ tinypng_gui.py GUI 程序
|
||
├─ tinypng_balancer.py 命令行和核心处理逻辑
|
||
├─ run_gui.bat 双击启动 GUI
|
||
├─ tinify_keys.json 实际 API Key 配置文件
|
||
├─ tinify_usage.json 本月额度缓存文件，运行后自动生成
|
||
├─ pyproject.toml uv 项目依赖配置
|
||
└─ uv.lock uv 锁定文件
|
||
```
|
||
|
||
## 启动 GUI
|
||
|
||
推荐直接双击：
|
||
|
||
```text
|
||
run_gui.bat
|
||
```
|
||
|
||
也可以在命令行运行：
|
||
|
||
```powershell
|
||
cd C:\dev\py\tinypng
|
||
uv run tinypng_gui.py
|
||
```
|
||
|
||
程序通过 `uv run` 启动，会自动使用 `pyproject.toml` 中声明的 `tinify` SDK 依赖。
|
||
|
||
## 配置 API Key
|
||
|
||
打开 GUI 后点击 `填写 API Key`。
|
||
|
||
支持以下输入方式：
|
||
|
||
```text
|
||
KEY_1
|
||
KEY_2
|
||
KEY_3
|
||
```
|
||
|
||
也支持用逗号、分号或空格分隔。保存后会生成 `tinify_keys.json`，主界面的“配置文件”会自动指向该文件。
|
||
|
||
配置文件格式示例：
|
||
|
||
```json
|
||
{
|
||
"api_keys": [
|
||
{
|
||
"key": "YOUR_TINIFY_API_KEY_1",
|
||
"monthly_limit": 500,
|
||
"name": "账号-1"
|
||
},
|
||
{
|
||
"key": "YOUR_TINIFY_API_KEY_2",
|
||
"monthly_limit": 500,
|
||
"name": "账号-2"
|
||
}
|
||
],
|
||
"proxy": null
|
||
}
|
||
```
|
||
|
||
不要把真实 API Key 写入 `tinify_keys.sample.json`，它只作为模板示例。
|
||
|
||
## GUI 使用流程
|
||
|
||
1. 把图片放入当前目录下的 `source` 文件夹。
|
||
2. 双击 `run_gui.bat` 打开界面。
|
||
3. 点击 `填写 API Key`，粘贴一个或多个 API Key 并保存。
|
||
4. 确认输入目录为 `source`。
|
||
5. 选择输出目录，默认是 `optimized`。
|
||
6. 按需选择转换格式、递归扫描、覆盖输出、同步官方额度等选项。
|
||
7. 点击 `开始处理`。
|
||
|
||
## 转换格式
|
||
|
||
`转换格式` 默认是 `保持原格式`。
|
||
|
||
可选值：
|
||
|
||
- `源格式`：只压缩，不改变格式。
|
||
- `png`：输出 PNG。
|
||
- `jpeg` / `jpg`：输出 JPEG。
|
||
- `webp`：输出 WebP。
|
||
- `avif`：输出 AVIF。
|
||
- 可多选，例如默认会同时选择 `源格式` 和 `webp`，每张图片会输出源格式压缩结果和 WebP 结果。
|
||
- 命令行的 `all` 会输出源格式、`.png`、`.jpg`、`.webp`、`.avif`。
|
||
|
||
注意：转换、缩放等 Tinify API 操作可能会消耗压缩额度。“全部格式”会为每张输入图片生成多个输出，因此额度消耗也会更多。
|
||
|
||
## 额度同步
|
||
|
||
GUI 默认勾选 `同步官方额度`。
|
||
|
||
处理开始前，程序会对每个 API Key 调用官方 SDK 的 `tinify.validate()`，然后读取 `tinify.compression_count`，同步该 Key 本月已经使用的数量。
|
||
|
||
同步后的额度会写入：
|
||
|
||
```text
|
||
tinify_usage.json
|
||
```
|
||
|
||
后续每次处理成功后，程序也会读取 SDK 更新后的 `tinify.compression_count` 并回写本地用量缓存。
|
||
|
||
## 命令行用法
|
||
|
||
压缩目录：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized
|
||
```
|
||
|
||
递归压缩：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --recursive
|
||
```
|
||
|
||
转换为 WebP：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --convert webp
|
||
```
|
||
|
||
同时输出源格式和 WebP：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --convert source --convert webp
|
||
```
|
||
|
||
输出全部格式：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --convert all
|
||
```
|
||
|
||
试运行：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --dry-run
|
||
```
|
||
|
||
跳过启动前官方额度同步：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --no-sync-usage
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 提示 No module named 'tinify'
|
||
|
||
请使用 `uv run` 启动：
|
||
|
||
```powershell
|
||
uv run tinypng_gui.py
|
||
```
|
||
|
||
或者双击 `run_gui.bat`。
|
||
|
||
### 没有找到图片
|
||
|
||
确认图片放在输入目录中。默认输入目录是：
|
||
|
||
```text
|
||
C:\dev\py\tinypng\source
|
||
```
|
||
|
||
支持的扩展名包括：
|
||
|
||
```text
|
||
.png .jpg .jpeg .webp .avif
|
||
```
|
||
|
||
### API Key 不可用
|
||
|
||
检查 `tinify_keys.json` 中是否写入了真实 Key。模板中的 `YOUR_TINIFY_API_KEY_1` 不能直接使用。
|
||
|
||
### 全部格式输出时额度消耗变多
|
||
|
||
这是正常的。因为每张图片会分别转换为 PNG、JPEG、WebP、AVIF 四种格式，每个输出都可能消耗 Tinify 额度。
|