picgo-plugin-imgproxy

一个 PicGo 的imgproxy处理插件 Replace PicGo copied URLs with imgproxy signed URLs after upload.

它会在图片上传成功后，读取 PicGo 最终准备复制到剪贴板的链接，并将其替换为 imgproxy 处理后的链接。插件既支持普通 HTTP/HTTPS 来源，也支持基于 S3 元数据生成 s3://bucket/key 类型的 imgproxy 来源。

功能概览

• 上传成功后自动将输出链接替换为 imgproxy 链接
• 支持 S3 来源（需插件picgo-plugin-s3-uploader配合）
• 仅处理识别为图片的上传项，非图片文件会跳过，避免对附件类文件误签名

安装

PicGo GUI / PicList

• 可以直接在插件设置页搜索安装 imgproxy、 picgo-plugin-imgproxy
• 也可以下载压缩包后解压本地导入

PicGo Core

picgo install picgo-plugin-imgproxy

配置项

| Key | 说明 | 示例 | | --- | --- | --- | | imgproxyBaseUrl | imgproxy 服务地址。允许带路径前缀，不允许带 query / hash。 | https://imgproxy.example.com | | imgproxyKey | 可选。十六进制格式的 IMGPROXY_KEY。若填写，必须与 imgproxySalt 同时填写。 | 943b...0881 | | imgproxySalt | 可选。十六进制格式的 IMGPROXY_SALT。若填写，必须与 imgproxyKey 同时填写。 | 520f...09c5 | | processingPath | imgproxy 处理参数。 | rs:fit:300:300 | | sourceUrlMode | HTTP 来源选择策略。current 优先 imgUrl，origin 优先 originImgUrl。 | current | | enableS3Source | 是否优先使用 S3 元数据构造 s3://bucket/key。 | true | | skipIfAlreadyImgproxy | 当前链接已经属于 imgproxyBaseUrl 时是否跳过。 | true | | debugLog | 是否输出调试日志。 | false |

说明：

• imgproxyKey 和 imgproxySalt 同时留空时，插件会自动使用 insecure 模式
• enableS3Source 默认关闭，避免把普通公开 URL 误判成 S3 来源
• 插件会优先基于 MIME / 扩展名识别是否为图片；如识别为非图片文件，则保留原始链接不做 imgproxy 处理

配置示例

{
  "picgo-plugin-imgproxy": {
    "imgproxyBaseUrl": "https://imgproxy.example.com",
    "imgproxyKey": "943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881",
    "imgproxySalt": "520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5",
    "processingPath": "rs:fit:300:300",
    "sourceUrlMode": "current",
    "enableS3Source": true,
    "skipIfAlreadyImgproxy": true,
    "debugLog": false
  }
}

来源解析顺序

当 enableS3Source = true 时，插件会按以下顺序寻找来源：

| 优先级 | 来源 | 说明 | | --- | --- | --- | | 1 | item.imgproxySource | 优先消费上传器直接写入的结构化来源元数据 | | 2 | picgo-plugin-s3-uploader | 识别 item.type === "s3-uploader"、item.uploadPath 和 picBed.s3-uploader.bucketName | | 3 | picgo-plugin-s3 | 兼容 item.type === "aws-s3" 的第三方插件输出 | | 4 | HTTP 来源 | 回退到 imgUrl / url / originImgUrl |

当 enableS3Source = false 时，插件只处理 HTTP/HTTPS 来源。

路径示例

| 来源类型 | 输入 | 生成的 imgproxy path | | --- | --- | --- | | HTTP | https://img.example.com/pretty/image.jpg | /rs:fit:300:300/plain/https://img.example.com/pretty/image.jpg | | S3 | bucket=public, key=img/Echo-idle-01.png | /rs:fit:300:300/plain/s3://public/img/Echo-idle-01.png |

与 S3 上传插件联用

如果你需要最稳的 S3 + imgproxy 链路，推荐与 picgo-plugin-s3-uploader一起使用。

picgo-plugin-s3-uploader 上传成功后会写入：

{
  "imgproxySource": {
    "backend": "s3",
    "bucket": "public",
    "key": "img/Echo-idle-01.png"
  }
}

本插件会直接消费这份元数据并生成：

/rs:fit:300:300/plain/s3://public/img/Echo-idle-01.png

兼容性说明

| 项目 | 说明 | | --- | --- | | 宿主兼容 | 已覆盖 PicGo GUI、PicGo Core、PicList 三类宿主入口 | | 插件列表兼容 | 已补齐 PicGo GUI / PicList 所需的 config 导出 | | 多插件并发 | 会主动让出一拍，尽量等待其他同步插件先完成 URL 改写 | | 重复执行保护 | 同一轮上传会做并发去重，避免重复签名 | | 禁用后残留 handler | 若宿主残留旧 handler，插件在禁用态会自跳过 | | 已签名判断 | 不只检查同域，还会校验路径首段是否像真实签名或 insecure |

调试建议

当你怀疑与其他插件冲突时，可以：

1. 打开 debugLog
2. 上传一张图片
3. 查看 PicGo 日志中是否包含：
   • 来源解析策略
   • 是否检测到其他插件已改写 URL
   • 是否命中 S3 来源适配
   • 被跳过的原因