常见问题与排查
从一个文件、一个图床、一个上传入口开始复现。先区分上传失败、结果保存失败和链接访问失败，再调整对应设置。
上传失败
| 现象 | 首先检查 |
|---|---|
| 首次使用无法上传 | 是否填写自己的凭据并设为默认 |
| 401 / 403 | Token、账号权限、有效期与访问策略 |
| 超时或连接失败 | Endpoint、代理、DNS 与目标服务可达性 |
| 某套配置失败 | 当前配置名、图床 ID 与路径 |
| 批量失败但单张成功 | 服务限流、文件大小与任务间隔 |
| 第二图床缺少结果 | 两个目标分别测试，检查第二图床日志 |
先临时关闭与问题有关的图片处理或自定义脚本，用小文件验证原始上传，再逐项恢复。
上传成功但图片无法访问
在服务端查看对象是否已存在；存在时检查生成的 URL，而不是反复上传。
- API Endpoint 与公开资源域名是否混用？
- 桶名或目录是否重复追加？
- 存储是私有读取还是公开读取？
- 签名 URL 是否已经过期？
- 复制的是 localhost 预览地址吗？
- 是否有 CDN 缓存、防盗链或必要的请求头？
图片处理
水印缺失检查字体或图片文件路径。压缩结果不符检查配置作用范围。格式转换失败检查平台可用编码器，不能由预览格式推断编码支持。
剪贴板
先把图片保存为文件上传。若文件成功，检查剪贴板里是图片内容、绝对路径、file:// URL 还是普通文本。Linux / 远程会话可能受桌面环境限制。
编辑器与服务
- 在 PicList 内测试上传。
- 用 /heartbeat 检查正确端口。
- 核对编辑器的完整可执行路径或 HTTP 地址。
- 远程访问发送 multipart 文件内容，不要发送客户端本地路径。
- Core 初始化、插件配置和 TUI 需要可交互终端。
桌面程序、独立 CLI、桌面 API 与 Core API 的要求不同，详见集成指南。
收尾失败与任务恢复
远端文件已存在且错误指出 finalization 时，优先恢复已有任务。API 客户端使用响应的 finalizationId。未确认上传状态前不要开启自动删源文件，也不要盲目重复整个队列。
提交问题
记录应用版本、系统、图床 ID、操作步骤和已脱敏的错误摘要。提供不含账号、密钥、二维码和私人文件名的截图。
不要附完整配置、原始 fullResult 或未检查的日志。桌面问题提交到 PicList Issues，独立 Core 问题提交到 Core Issues。