Skip to content

eyunzhu/picgo-plugin-s3-uploader

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
lib
lib
 
 
test
test
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
index.js
index.js
 
 
package.json
package.json
 
 

Repository files navigation

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

About

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

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.1 Latest
Mar 31, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages
⚡