1016 字
3 分钟
Komga 封面上传压缩的油猴脚本
Komga 封面上传压缩的油猴脚本
你还在为 Komga 上传文件限制大小而烦恼吗？拖了一张精美的漫画封面上去，结果反代报 413 或者 Nginx 直接拒收——改服务器配置太麻烦，每次手动压缩又费时费力。这个油猴脚本就是为了终结这个问题而生的。
下载本文所使用的脚本：komga-cover-compress-upload.user.js（约 22 KB）。
脚本做了什么
脚本在 Komga 的系列列表和书籍卡片上自动注入一个蓝色上传按钮，点击后选择本地图片，脚本会在浏览器端自动将图片压缩到 1 MiB 以内，然后直接上传到 Komga 的封面接口并自动设为选中封面。
核心流程就三步：
- 自动扫描页面：脚本通过 MutationObserver + 定时轮询，持续扫描 Komga 页面上的系列卡片和书籍卡片，在每一张卡片的合适位置插入一个上传按钮。
- 浏览器端压缩：选择图片后，在 Canvas 上以 90% 的倍率逐次缩小图片尺寸，直到输出 JPEG 文件大小 ≤ 1 MiB。压缩过程中还会抽样检查画布像素，防止浏览器生成空白图。
- 上传 + 选中：压缩完成后，通过
POST /api/v1/{series|books}/{id}/thumbnails上传封面，再调用PUT .../thumbnails/{thumbnailId}/selected设为选中封面，并自动刷新页面上的缩略图缓存。
原理简述
压缩策略
原始图片 > 1 MiB？ → 缩放到 90%，输出 JPEG（quality=0.92） → 仍然 > 1 MiB？ → 再缩放到 81%（0.9 × 0.9），继续尝试 → 最多尝试 50 次 → 尺寸低于 64px 时放弃这种”等比缩放 + 固定质量”的策略比单纯降低 JPEG 质量更可靠——降低质量到一定程度后文件大小几乎不再变化，而缩小尺寸的效果是线性的。
页面按钮注入
脚本不依赖 Komga 的前端框架内部结构，而是通过选择器匹配图片 URL 中的 /api/v1/books/ 和 /api/v1/series/ 路径来定位卡片，兼容性好，Komga 版本升级一般不受影响。按钮默认透明隐藏，鼠标悬停在卡片上时才显示，不影响正常浏览体验。
缓存刷新
上传成功后，脚本会在 localStorage 记录该条目 24 小时内更新过，给页面上的缩略图请求追加 _kcu 参数绕过反代缓存，确保你立刻看到新封面。
怎么用
第一步：安装脚本
- 打开 Tampermonkey（没有的话先去 Tampermonkey 官网 安装浏览器扩展）。
- 点击 Tampermonkey 图标 → 「创建新脚本」。
- 把
komga-cover-compress-upload.user.js的全部内容复制进去，替换默认模板。 - 保存（Ctrl+S）。
记得把脚本第 7 行的
@match改成你自己的域名。
第二步：使用
- 打开 Komga 页面，进入系列列表或某个系列的书籍列表。
- 鼠标悬停在任意书籍/系列卡片上，你会看到右侧出现一个蓝色圆形上传按钮（↑ 图标）。
- 点击按钮，选择本地图片。
- 等待提示「压缩中…」→「准备上传…」→「封面已上传、选中并验证保存」。
- 页面上的封面缩略图自动刷新。
注意事项
- 需要你的 Komga 账号有 ADMIN 权限。
- 脚本使用浏览器当前登录态，不会保存你的账号密码。
- 压缩输出统一为 JPEG 格式，透明背景会被填充为白色——带透明通道的 PNG 封面建议提前处理好。
- 如果图片实在太大（比如 10000×10000 的原图），压缩到 64px 宽还超 1 MiB 的话，脚本会提示失败，这时候需要手动预处理一下图片。
总结
所有操作在浏览器本地完成，不依赖任何第三方服务，安全、轻量、开箱即用。如果你也有 Komga 封面管理的需求，不妨试试。
Komga 封面上传压缩的油猴脚本
https://blog.patlabor.cn/posts/Komga 封面上传压缩油猴脚本/ 部分信息可能已经过时