picgo-plugin-s3-uploader

v1.0.1

Published

2 months ago

S3-compatible PicGo uploader that emits imgproxy-friendly source metadata.

0High
0Medium
0Low

eyunzhu

picgo picgo-core picgo-gui-plugin picgo-plugin s3-uploader piclist s3 uploader aws garage minio imgproxy

picgo-plugin-s3-uploader

一个面向 AWS S3、Garage、MinIO 等 S3 兼容对象存储的 PicGo 插件，支持文件上传、删除，以及输出 imgproxy 等插件使用的数据字段

它负责把文件上传到 S3 兼容服务，并输出：

正常可访问的 url / imgUrl
供 picgo-plugin-imgproxy 使用的稳定 imgproxySource

功能概览

支持 AWS S3 / Garage / MinIO 等 S3 兼容服务
支持 PicGo GUI 删除文件时同步执行 S3 DELETE Object
支持 uploadPath 上传路径模板
支持 outputURLPattern 自定义输出 URL 模板
常见图片、视频、音频、文档、压缩包、网页资源类型会自动写入合适的 Content-Type
可选写入 Content-Disposition: inline，让浏览器更倾向于直接预览
内置中英文文案，并优先跟随 PicGo / PicList 当前语言设置

安装

PicGo GUI / PicList

可以直接在插件设置页安装 s3-uploader
也可以安装完整包名 picgo-plugin-s3-uploader

PicGo Core

picgo install picgo-plugin-s3-uploader

配置项

| Key | 说明 | 示例 | | --- | --- | --- | | accessKeyID | S3 Access Key。 | YOUR_ACCESS_KEY | | secretAccessKey | S3 Secret Key。 | YOUR_SECRET_KEY | | bucketName | 目标 bucket 名称。 | public | | uploadPath | 上传路径模板，可使用占位符。 | img/{year}/{month}/{md5}.{ext} | | outputURLPattern | 自定义输出 URL 模板；为空时按默认规则推导公开 URL。 | https://cdn.example.com/{encodedKey} | | region | 签名区域。AWS 常见为 us-east-1；Garage 为 garage。 | us-east-1 | | endpoint | S3 API Endpoint。AWS S3 可留空。必须是完整的 http:// 或 https:// 地址。 | https://minio.example.com | | pathStyleAccess | 是否使用 path-style 请求。Garage / MinIO 常见为 true。 | true | | rejectUnauthorized | 是否拒绝无效 TLS 证书。 | true | | acl | 对象 ACL；若服务不支持可留空。 | public-read | | contentDispositionInline | 是否在上传时写入 Content-Disposition: inline。 | false |

配置示例

Garage

{
  "picBed": {
    "current": "s3-uploader",
    "uploader": "s3-uploader",
    "s3-uploader": {
      "accessKeyID": "YOUR_ACCESS_KEY",
      "secretAccessKey": "YOUR_SECRET_KEY",
      "bucketName": "public",
      "uploadPath": "img/{year}/{month}/{md5}.{ext}",
      "outputURLPattern": "https://{bucket}.example.com/{encodedKey}",
      "region": "garage",
      "endpoint": "https://garage-api.example.com",
      "pathStyleAccess": true,
      "rejectUnauthorized": true,
      "acl": "public-read",
      "contentDispositionInline": true
    }
  }
}

MinIO

{
  "picBed": {
    "current": "s3-uploader",
    "uploader": "s3-uploader",
    "s3-uploader": {
      "accessKeyID": "YOUR_ACCESS_KEY",
      "secretAccessKey": "YOUR_SECRET_KEY",
      "bucketName": "public",
      "uploadPath": "img/{year}/{month}/{fileName:/\\s+/g,'-'}.{extName}",
      "outputURLPattern": "https://cdn.example.com/{encodedKey}",
      "region": "us-east-1",
      "endpoint": "https://minio.example.com",
      "pathStyleAccess": true,
      "rejectUnauthorized": true,
      "acl": "public-read",
      "contentDispositionInline": true
    }
  }
}

AWS S3

{
  "picBed": {
    "current": "s3-uploader",
    "uploader": "s3-uploader",
    "s3-uploader": {
      "accessKeyID": "YOUR_ACCESS_KEY",
      "secretAccessKey": "YOUR_SECRET_KEY",
      "bucketName": "public",
      "uploadPath": "img/{year}/{month}/{uuidN}.{extName}",
      "outputURLPattern": "https://cdn.example.com/{encodedKey}",
      "region": "us-east-1",
      "pathStyleAccess": false,
      "rejectUnauthorized": true,
      "acl": "public-read",
      "contentDispositionInline": true
    }
  }
}

预览与下载

浏览器是“直接预览”还是“弹出下载”，主要取决于对象响应头：

Content-Type 是否正确，例如 video/mp4、application/pdf
Content-Disposition 是否被设置为 attachment 或 inline

本插件默认不会强行写 Content-Disposition，而是优先依赖正确的 Content-Type。如果你希望浏览器更明确地按预览处理，可以开启 contentDispositionInline。

模板语法

uploadPath 与 outputURLPattern 共用同一套模板语法。

通用占位符

以下占位符在 uploadPath 与 outputURLPattern 中都可使用。

| 分类 | 占位符 | | --- | --- | | 时间 | {year} {month} {day} {hour} {minute} {second} {millisecond} {timestamp} {timestampMS} | | 文件 | {fullName} {fileName} {filename} {basename} {name} {extName} {ext} | | 哈希 | {crc32} {md5} {md5B64} {md5B64Short} {sha1} {sha256} | | 上传上下文 | {bucket} {region} {acl} {contentType} {mime} {size} {uuid} {uuidN} | | Endpoint | {endpoint} {endpointOrigin} {endpointProtocol} {endpointHost} {endpointHostname} {endpointPort} {endpointPath} {pathStyleAccess} |

`outputURLPattern` 专属占位符

| 占位符 | 说明 | | --- | --- | | {url} | 插件按默认规则推导出的公开 URL | | {origin} {protocol} {host} {hostname} {port} | 默认公开 URL 的主机信息 | | {pathname} | 默认公开 URL 的路径部分，带前导 / | | {path} | 默认公开 URL 的路径部分，不带前导 / | | {key} {objectKey} {uploadPath} | 对象 key，未编码 | | {encodedKey} | URL 安全的对象 key | | {dir} | 对象 key 的目录部分，未编码 | | {encodedDir} | URL 安全的目录部分 | | {bucketPath} | bucket/key | | {encodedBucketPath} | URL 安全的 bucket/key | | {eTag} {etag} | 上传返回的 eTag |

模板操作语法

下面用一组固定输入说明模板操作语法：

| 字段 | 示例值 | | --- | --- | | bucket | public-bucket | | md5 | 2095312189753de6ad47dfe20cbe97ec | | fileName | Echo idle 01 | | fullName | Echo idle 01.png |

| 写法 | 输入 | 结果 | 说明 | | --- | --- | --- | --- | | {bucket} | bucket = public-bucket | public-bucket | 直接取值 | | {md5:8} | md5 = 2095312189753de6ad47dfe20cbe97ec | 20953121 | 取前 8 位 | | {md5:0,8} | md5 = 2095312189753de6ad47dfe20cbe97ec | 20953121 | 从第 0 位开始取 8 位 | | {fileName:/\\s+/g,'-'} | fileName = Echo idle 01 | Echo-idle-01 | 把连续空格替换为 - | | {fullName:/\\s+/g,'_'} | fullName = Echo idle 01.png | Echo_idle_01.png | 把连续空格替换为 _ | | {fullName:/[^A-Za-z0-9._-]+/g,''} | fullName = Echo idle 01.png | Echoidle01.png | 移除空格和其他不在白名单内的字符 |

说明：

{name:8} 等价于 {name:0,8}
正则写法中的 flags 可省略
replacement 需要写在单引号里

常见模板示例

| 场景 | 模板 | 结果示例 | | --- | --- | --- | | 按年月归档 | img/{year}/{month}/{fullName} | img/2026/03/Echo idle 01.png | | 用 md5 作为文件名 | img/{year}/{month}/{md5}.{ext} | img/2026/03/2095312189753de6ad47dfe20cbe97ec.png | | 把空格替换为 - | img/{fileName:/\\s+/g,'-'}.{extName} | img/Echo-idle-01.png | | 输出到 CDN | https://cdn.example.com/{encodedKey} | https://cdn.example.com/img/Echo-idle-01.png | | bucket 作为子域名 | https://{bucket}.cdn.example.com/{encodedKey} | https://public.cdn.example.com/img/Echo-idle-01.png |

`outputURLPattern` 使用建议

如果你是在拼装最终公开 URL，优先使用：

| 推荐占位符 | 原因 | | --- | --- | | {encodedKey} | 对中文、空格和特殊字符更安全 | | {path} / {pathname} | 可以直接复用默认推导出的路径结构 | | {encodedBucketPath} | 适合自行拼接 bucket/key |

`endpoint` 规则

| 项目 | 说明 | | --- | --- | | 填写内容 | endpoint 填的是 S3 API 地址，不是 CDN 域名或公开访问域名 | | AWS S3 | 可留空，插件会根据 region 自动推导 | | 协议要求 | 必须写完整的 http:// 或 https:// | | 禁止内容 | 不允许带 query / hash | | 域名分离场景 | 如果公开访问域名和 API 地址不同，请把公开域名写到 outputURLPattern | | 自动归一化 | 若误把 bucket 写进 endpoint 的 host 或 path，插件会自动去重 |

默认公开 URL 推导规则

当 outputURLPattern 为空时：

| 条件 | 结果 | | --- | --- | | endpoint 已设置，pathStyleAccess = true | https://endpoint/bucket/key | | endpoint 已设置，pathStyleAccess = false | https://bucket.endpoint/key | | endpoint 未设置 | 按 AWS 官方 S3 域名规则结合 region 自动推导 |

如果你的 API Endpoint、公开访问域名、CDN 域名不是同一个地址，建议显式配置 outputURLPattern。

上传成功后写入的字段

这些字段可供其他插件继续消费，尤其是 picgo-plugin-imgproxy。

| 字段 | 说明 | 示例 | | --- | --- | --- | | uploadPath | 对象 key | img/Echo-idle-01.png | | eTag | 上传返回的 eTag | etag-value | | imgproxySource.backend | 固定为 s3 | s3 | | imgproxySource.bucket | bucket 名称 | public | | imgproxySource.key | 对象 key | img/Echo-idle-01.png |

对应的 S3 来源统一为：

s3://bucket/key

删除支持

PicGo GUI 删除文件时，本插件会监听 remove 事件，并对当前插件上传的对象执行 S3 DELETE Object。

| 行为 | 说明 | | --- | --- | | 删除范围 | 只处理 type === "s3-uploader" 的项目 | | key 来源 | 优先使用 imgproxySource.key，没有时回退到 uploadPath | | 不存在对象 | 记为“已不存在”，不视为硬错误 | | 用户反馈 | 会同时写日志，并在 GUI 中弹出通知 |

与 picgo-plugin-imgproxy 联用

当你同时安装：

picgo-plugin-s3-uploader
picgo-plugin-imgproxy

并在 picgo-plugin-imgproxy 中开启：

{
  "enableS3Source": true
}

imgproxy 插件会优先读取本插件写出的：

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

并据此生成s3格式的链接进行处理：

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

picgo-plugin-s3-uploader

功能概览

安装

PicGo GUI / PicList

PicGo Core

配置项

配置示例

Garage

MinIO

AWS S3

预览与下载

模板语法

通用占位符

outputURLPattern 专属占位符

模板操作语法

常见模板示例

outputURLPattern 使用建议

endpoint 规则

默认公开 URL 推导规则

上传成功后写入的字段

删除支持

与 picgo-plugin-imgproxy 联用

`outputURLPattern` 专属占位符

`outputURLPattern` 使用建议

`endpoint` 规则