326 lines
7.6 KiB
Markdown
326 lines
7.6 KiB
Markdown
# TinyPNG 批量压缩工具
|
||
|
||
这是一个基于 Tinify/TinyPNG Python SDK 的批量图片压缩和格式转换工具。它提供图形界面和命令行两种使用方式，支持多个 API Key 接力使用、官方额度同步、批量格式转换、递归处理目录、HTTP/SOCKS5 代理，以及 Windows 二进制打包分发。
|
||
|
||
## 功能
|
||
|
||
- GUI 图形界面，适合日常批量处理图片。
|
||
- CLI 命令行入口，适合脚本化或自动化处理。
|
||
- 支持多个 Tinify API Key，每个 Key 默认每月 500 张额度。
|
||
- 支持处理前同步官方本月已用额度。
|
||
- 支持 PNG、JPG/JPEG、WebP、AVIF 输入。
|
||
- 支持输出源格式、PNG、JPEG、WebP、AVIF，也可以一次输出全部格式。
|
||
- 支持递归扫描目录。
|
||
- 支持覆盖已有输出文件或跳过已有文件。
|
||
- 支持试运行，只预览处理计划，不调用 Tinify API。
|
||
- 支持 HTTP 代理和 SOCKS5 代理。
|
||
|
||
## 目录说明
|
||
|
||
```text
|
||
C:\dev\py\tinypng
|
||
├─ source\ 默认输入目录，把待处理图片放这里
|
||
├─ optimized\ 默认输出目录，运行后自动生成
|
||
├─ tinypng_gui.py GUI 程序
|
||
├─ tinypng_balancer.py 命令行和核心处理逻辑
|
||
├─ run_gui.bat 双击启动 GUI
|
||
├─ tinify_keys.sample.json API Key 配置模板
|
||
├─ tinify_keys.json 实际 API Key 配置文件，本地使用，不提交 Git
|
||
├─ tinify_usage.json 本月额度缓存文件，本地使用，不提交 Git
|
||
├─ pyproject.toml uv 项目依赖配置
|
||
└─ uv.lock uv 锁定文件
|
||
```
|
||
|
||
打包后使用 `--onedir` 文件夹版时，默认目录会改为可执行文件所在目录：
|
||
|
||
```text
|
||
dist\tinypng-gui
|
||
├─ tinypng-gui.exe
|
||
├─ _internal\
|
||
├─ source\
|
||
├─ optimized\
|
||
├─ tinify_keys.json
|
||
└─ tinify_usage.json
|
||
```
|
||
|
||
`source`、`optimized` 和 JSON 配置文件不会放到 `_internal` 里。
|
||
|
||
## 安装依赖
|
||
|
||
项目使用 `uv` 管理依赖：
|
||
|
||
```powershell
|
||
cd C:\dev\py\tinypng
|
||
uv sync
|
||
```
|
||
|
||
主要依赖：
|
||
|
||
- `tinify`：TinyPNG 官方 Python SDK。
|
||
- `requests[socks]`：为 HTTP/SOCKS5 代理提供支持。
|
||
|
||
## 启动 GUI
|
||
|
||
推荐直接双击：
|
||
|
||
```text
|
||
run_gui.bat
|
||
```
|
||
|
||
也可以在命令行运行：
|
||
|
||
```powershell
|
||
cd C:\dev\py\tinypng
|
||
uv run tinypng_gui.py
|
||
```
|
||
|
||
## 配置 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`，它只作为模板示例。
|
||
|
||
## 代理格式
|
||
|
||
不需要代理时留空。
|
||
|
||
HTTP 代理：
|
||
|
||
```text
|
||
http://127.0.0.1:7890
|
||
```
|
||
|
||
SOCKS5 代理：
|
||
|
||
```text
|
||
socks5://127.0.0.1:1080
|
||
```
|
||
|
||
带账号密码：
|
||
|
||
```text
|
||
http://username:password@127.0.0.1:7890
|
||
socks5://username:password@127.0.0.1:1080
|
||
```
|
||
|
||
常见代理软件的 HTTP 端口可能是 `7890`、`10809`，SOCKS5 端口可能是 `1080`、`10808`。以代理软件里实际显示的端口为准。
|
||
|
||
## GUI 使用流程
|
||
|
||
1. 把图片放入 `source` 文件夹，或在界面中选择其他输入目录。
|
||
2. 点击 `填写 API Key`，粘贴一个或多个 API Key 并保存。
|
||
3. 如需代理，在代理输入框填写 HTTP 或 SOCKS5 地址。
|
||
4. 确认输出目录，默认是 `optimized`。
|
||
5. 按需选择转换格式、递归扫描、覆盖输出、试运行、同步官方额度等选项。
|
||
6. 点击 `开始处理`。
|
||
|
||
## 转换格式
|
||
|
||
`转换格式` 默认选择 `源格式` 和 `webp`。
|
||
|
||
可选值：
|
||
|
||
- `源格式`：只压缩，不改变格式。
|
||
- `png`：输出 PNG。
|
||
- `jpeg` / `jpg`：输出 JPEG。
|
||
- `webp`：输出 WebP。
|
||
- `avif`：输出 AVIF。
|
||
- `all`：命令行专用，一次输出源格式、PNG、JPEG、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 --resize-method fit --width 1200 --height 1200
|
||
```
|
||
|
||
试运行：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --dry-run
|
||
```
|
||
|
||
跳过启动前官方额度同步：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --no-sync-usage
|
||
```
|
||
|
||
指定配置和用量文件：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py source -o optimized --config tinify_keys.json --state tinify_usage.json
|
||
```
|
||
|
||
生成配置模板：
|
||
|
||
```powershell
|
||
uv run tinypng_balancer.py --init-config tinify_keys.json
|
||
```
|
||
|
||
## 打包 Windows 二进制
|
||
|
||
推荐打包为 `onedir` 文件夹版：
|
||
|
||
```powershell
|
||
uv run --with pyinstaller pyinstaller --noconfirm --clean --onedir --windowed --name tinypng-gui --collect-data tinify --add-data "tinify_keys.sample.json;." tinypng_gui.py
|
||
```
|
||
|
||
输出目录：
|
||
|
||
```text
|
||
dist\tinypng-gui\
|
||
```
|
||
|
||
启动文件：
|
||
|
||
```text
|
||
dist\tinypng-gui\tinypng-gui.exe
|
||
```
|
||
|
||
分发时需要把整个 `dist\tinypng-gui\` 文件夹一起发出去，因为 `_internal\` 里包含运行依赖。
|
||
|
||
不推荐日常使用 `--onefile` 单文件版。单文件版启动时会先解压依赖到系统临时目录；文件夹版不会把依赖释放到 Temp，路径也更容易管理。
|
||
|
||
## Git 忽略
|
||
|
||
以下文件通常不需要提交：
|
||
|
||
```gitignore
|
||
tinify_keys.json
|
||
tinify_usage.json
|
||
optimized
|
||
source
|
||
build/
|
||
dist/
|
||
*.spec
|
||
*.exe
|
||
```
|
||
|
||
`pyinstaller` 只在打包时临时安装和使用，不需要作为项目依赖提交。
|
||
|
||
## 常见问题
|
||
|
||
### 提示 No module named 'tinify'
|
||
|
||
请使用 `uv run` 启动：
|
||
|
||
```powershell
|
||
uv run tinypng_gui.py
|
||
```
|
||
|
||
或者双击 `run_gui.bat`。
|
||
|
||
### 填写 socks5:// 代理后提示缺少 SOCKS 支持
|
||
|
||
确认已经安装 SOCKS 依赖：
|
||
|
||
```powershell
|
||
uv sync
|
||
```
|
||
|
||
如果是旧环境，可以重新添加依赖：
|
||
|
||
```powershell
|
||
uv add requests[socks]
|
||
```
|
||
|
||
然后重新打包二进制。
|
||
|
||
### 打包版路径指向 _internal
|
||
|
||
请使用新版代码重新打包。GUI 会在打包环境中使用 `tinypng-gui.exe` 所在目录作为默认目录，不会把 `source`、`optimized`、`tinify_keys.json` 放进 `_internal`。
|
||
|
||
### 没有找到图片
|
||
|
||
确认图片放在输入目录中。支持的扩展名包括：
|
||
|
||
```text
|
||
.png .jpg .jpeg .webp .avif
|
||
```
|
||
|
||
### API Key 不可用
|
||
|
||
检查 `tinify_keys.json` 中是否写入了真实 Key。模板中的 `YOUR_TINIFY_API_KEY_1` 不能直接使用。
|
||
|
||
### 全部格式输出时额度消耗变多
|
||
|
||
这是正常的。因为每张图片会分别转换为多个格式，每个输出都可能消耗 Tinify 额度。
|