picgo-plugin-s3

picgo-plugin-s3

PicGo Amazon S3 上传插件。

• 支持 Amazon S3 与其他兼容 S3 API 的云存储 (例如 Backblaze B2)。
• 支持 PicGo GUI。
• 支持 MinIO。

安装 (Installation)

GUI 用户可直接在插件市场搜索 s3 并下载。

Core 用户可执行 picgo add s3 命令安装。

配置 (Configuration)

picgo set uploader s3

Key	说明	示例
accessKeyID	AWS 凭证 ID。
secretAccessKey	AWS 凭证密钥。
bucketName	S3 桶名称。	gallery
uploadPath	上传路径，详细配置请查看以下说明。	{year}/{month}/{fullName}
endpoint	指定自定义终端节点。	s3.us-west-2.amazonaws.com
proxy	代理地址，支持 http 代理。	http://127.0.0.1:1080
region	指定执行服务请求的区域。	us-west-1
pathStyleAccess	是否启用 S3 Path style 访问模式。 例如 https://s3.amazonaws.com/<bucketName>/<key>。 使用 MinIO 时请设置为 true。	默认为 false
rejectUnauthorized	是否拒绝无效的 TLS 证书连接。 如上传失败日志显示证书问题可设置为 false。	默认为 true
acl	访问控制列表 (ACL)，用于设置资源的访问策略。 可选值: private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control。	默认为 public-read
outputURLPattern	自定义输出 URL 模板，详细配置请查看以下说明。	{protocol}://{host}:{port}/{path}
urlPrefix	[已废弃] 自定义 URL 前缀。请使用 outputURLPattern。	https://img.example.com/my-blog/
urlSuffix	[已废弃] 自定义 URL 后缀。请使用 outputURLPattern。	?oxx=xxx
disableBucketPrefixToURL	[已废弃] 禁用 URL 中的 bucket 前缀。请使用 outputURLPattern。	默认为 false

---

通用占位符

uploadPath 和 outputURLPattern 均支持通用占位符，插件会将其替换为实际变量。

占位符	描述
{year}	年
{month}	月
{day}	日
{hour}	时
{minute}	分
{second}	秒
{millisecond}	毫秒
{timestamp}	Unix 时间戳 (秒)
{timestampMS}	Unix 时间戳 (毫秒)

上传路径 (uploadPath)

除了通用占位符外，还支持以下变量：

占位符	描述
{fullName}	完整文件名 (含扩展名)
{fileName}	文件名 (不含扩展名)
{extName}	扩展名 (不含 .)
{md5}	图片 MD5
{sha1}	图片 SHA1
{sha256}	图片 SHA256

对于 MD5、SHA1、SHA256，支持这几种截断方式：

• {sha256:2}：从第三个字符开始，例如 abcd -> cd
• {sha256:2,4}：从第三个字符开始，截取长度为4，例如 abcdefgh

---

自定义输出 URL 模板 (outputURLPattern)

此配置将替代已废弃的 urlPrefix、urlSuffix 和 disableBucketPrefixToURL。

除了通用占位符外，还支持以下变量：

占位符	描述	示例
{protocol}	URL 协议	http 或 https
{host}	URL 域名	s3.amazonaws.com
{port}	URL 端口	80
{dir}	上传目录	xxx/2024/12
{uploadedFileName}	上传后的文件名 (含扩展名)	4aa4f41e38817e5fd38ac870f40dbc70.jpg
{path}	完整路径 ({dir}/{uploadedFileName})	xxx/2024/12/4aa4f41e38817e5fd38ac870f40dbc70.jpg
{fileName}	源文件名 (含扩展名)	test.jpg
{extName}	源文件扩展名 (不含 .)	jpg
{query}	URL 查询参数 (不含 ?)	height=100&width=200
{hash}	URL hash (不含 #)	abc
{bucket}	S3 桶名	my-bucket

正则替换

每个变量都支持通过正则表达式进行替换(正则替换表达式中间不能有空格)。

语法:

{payload:/pattern/flags,'replacement'}

示例: 假设配置为 {protocol}://example.com/{path:/testBucket/i,'myimage'}， 并且原始 URL 为 https://cluster.s3.example.com/testBucket/image.jpg， 则最终生成的 URL 为 https://example.com/myimage/image.jpg。

---

完整示例 (Example)

{
  "picgo-plugin-s3": {
    "accessKeyID": "xxx",
    "secretAccessKey": "xxxxx",
    "bucketName": "my-bucket",
    "uploadPath": "{year}/{md5}.{extName}",
    "endpoint": "s3.us-west-000.backblazeb2.com",
    "outputURLPattern": "https://img.example.com/{bucket}/{path}"
  }
}

如果 PicGo 按以上配置，上传 sample.png，最终得到的图片地址可能为：https://img.example.com/my-bucket/2021/4aa4f41e38817e5fd38ac870f40dbc70.png。

发布 (Publish)

执行以下任一命令，会自动更新 package.json 的版本号并生成一个 commit 推送到远程仓库。GitHub Action 将会自动编译、打包并发布到 NPM。

# 更新补丁版本 (patch)
npm run patch

# 更新次要版本 (minor)
npm run minor

# 更新主要版本 (major)
npm run major

开发 (Development)

1. Clone this repo
2. npm i && npm run dev
3. cd ~/.picgo && npm install ${path_to_the_repo}

贡献 (Contributing)

欢迎提交 Pull Request。对于重大更改，请先开一个 Issue 进行讨论。

许可证 (License)

Released under the MIT License.