img 0.4 使用指南

img 将图床管理、常用图片处理和文章引用维护放在同一套桌面与 CLI 工作流中。桌面版包含同版本 CLI；两者读取相同存储配置与 SQLite 图库。

图库

在「存储源」连接 S3/R2/OSS、GitHub 或 WebDAV，并选择需要索引的目录。自定义 HTTP 源保留已知上传记录，不提供服务端未支持的浏览和删除。

图库搜索基于已索引范围。首次索引可以暂停、继续；桌面运行期间定期刷新，退出后停止。扫描失败不会把图片当作已删除。记录里的远端位置是依据，本机缓存只用于加速预览；清缓存、隐藏记录和删除远端文件是三个不同操作。

切换网格、列表和搜索会保留选择。复制、下载、检查、迁移和删除在开始时固定目标。多地址图片优先使用当前存储筛选匹配的地址，否则使用首选地址。删除前确认具体图床和对象，版本改变或存在上传任务时会拒绝执行。

img library index --provider oss --prefix articles/
img library list --provider oss --search cover --limit 100
img library show IMAGE_ID
img library check IMAGE_ID
img library download IMAGE_ID --output-dir ./downloads
img library cache --clear

转换与压缩、尺寸与裁剪

两个工具位于侧边栏，与图库、上传同级。一次打开或粘贴一张图片，两个工具共用图片和参数；更换图片会重置裁剪、旋转和翻转。左侧显示预览，右侧调整参数，右下显示实际输出大小及保存、复制、上传操作。

完整处理 PNG、JPEG 和静态 WebP。JPEG 的透明区域默认填白，可以更改颜色。
目标大小模式保留格式和尺寸：JPEG/有损 WebP 搜索质量，PNG 保持无损。无法达到目标时明确提示。
支持最长边或指定宽高、保持比例、自由或固定比例裁剪、90°旋转、水平/垂直翻转。默认不放大小图。
所有操作从原始输入重新计算；预览与导出使用同一套处理逻辑。原文件保持不变。
上传会先准备当前处理结果，再选择存储源，无需先保存到本地目录。结果使用新路径，不自动覆盖远端对象。

GIF、动态 WebP、SVG、AVIF 可以原样上传；这两个编辑工具不把动画扁平化，也不提供 HEIC、图层或 AI 修图。

保留原有 CLI 用法：

img process photo.png --output photo.webp --image-format webp
img process photo.png --recipe recipe.json --output-dir ./output
img tasks list
img tasks show TASK_ID

最小配方示例（recipe.json）：

{
  "version": 1,
  "encoding": {
    "format": "webp",
    "compression": { "mode": "quality", "quality": 85 }
  }
}

配方字段以 CLI 接受的 ProcessingPlan 为准；完整定义见 crates/img-records/src/processing.rs。桌面预设不加载已移出界面的标注、切分、拼接或独立水印操作。

同步

在「设置 → 同步」使用专用 WebDAV 目录或 S3 前缀，验证连接后同步。同步配置、图床凭据、索引、隐藏状态、首选地址和预设；不传输图片缓存、本机文件路径或运行中的任务。连接同步存储的凭据只保存在各设备。

同步的图床凭据以明文保存在用户的同步目录。 img 不额外加密，需将目录设为私有。本机凭据仍由系统凭据管理器保存，环境变量引用保持引用，不会自动导出环境变量的值。

冲突保留两边内容，用户选择后收敛；不以设备时钟强行覆盖。同步接收到删除记录不会代替用户删除远端图片。桌面退出后后台同步停止。

img sync status
img sync run
img sync conflicts

迁移与文章修复

先选择图库图片和目标图床，预览目的路径和冲突，再执行复制。验证新图片成功后才生成链接映射；默认保留源端文件，重试保留已成功的结果。

img migrate plan IMAGE_ID --to r2 --prefix articles --output move.json
img migrate apply move.json --report report.json
img migrate show TASK_ID
img references scan ./articles --migration TASK_ID --output references.json
img references show REFERENCE_TASK_ID
img references apply REFERENCE_TASK_ID --yes
img references export REFERENCE_TASK_ID ./repair-report
img references restore REFERENCE_TASK_ID

只扫描指定目录内的 .md 和 .markdown，识别行内、引用式图片及 HTML <img src>，跳过代码。应用前再次检查文档和目标图片；备份成功后原子替换，失败项保留原引用。恢复同样先预览，再通过 references apply --yes 执行，并备份恢复前的内容。

目录外的引用不在检查范围内，不能据此判断图片可安全删除。无法取得原图、可访问副本或匹配内容哈希的缓存时，不承诺恢复丢失图片。

安装与更新

安装页始终解析最新稳定版，无需每次修改下载链接。三端安装包与独立 CLI 由 GitHub Actions 生成，并附校验文件。桌面设置页提供检查更新和添加终端命令。

社区版 macOS 未经过 Apple 公证，Windows 未代码签名；首次安装说明见安装页。升级前可导出备份。CLI 恢复要求关闭桌面应用，包含凭据的备份需显式选择并妥善保存。