picgo-plugin-s3
Version:
picgo amazon s3 uploader
130 lines (97 loc) • 10.3 kB
Markdown
## picgo-plugin-s3
[](https://www.npmjs.com/package/picgo-plugin-s3)
[PicGo](https://github.com/PicGo/PicGo-Core) Amazon S3 上传插件。
- 支持 Amazon S3 与其他如 backblaze b2 等兼容 S3 API 的云存储
- 支持 PicGO GUI
- 支持 MinIO
### 安装 Installation
GUI 直接搜索 _S3_ 下载即可，Core 版执行 `picgo add s3` 安装。
### 配置 Configuration
```sh
picgo set uploader aws-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 | 默认为 `false`，使用 minio 请设置为 `true` (e.g., https://s3.amazonaws.com/<bucketName>/<key> instead of https://<bucketName>.s3.amazonaws.com/<key>) |
| `rejectUnauthorized` | 是否拒绝无效 TLS 证书连接 | 默认为 `true`，如上传失败日志显示证书问题可设置为`false` |
| `acl` | 访问控制列表，上传资源的访问策略 | 默认为 `public-read`, AWS 可选 `private" | "public-read" | "public-read-write" | "authenticated-read" | "aws-exec-read" | "bucket-owner-read" | "bucket-owner-full-control` |
| `outputURLPattern` | 自定义输出 URL 模板，详细配置查看以下说明 | `{protocol}://{host}:{port}/{path}` |
| `urlPrefix` | 最终生成图片 URL 的自定义前缀（已废弃，请使用 outputURLPattern） | `https://img.example.com/my-blog/` |
| `urlSuffix` | 最终生成图片 URL 的自定义后缀（已废弃，请使用 outputURLPattern） | `?oxx=xxx` |
| `disableBucketPrefixToURL` | 开启 `pathStyleAccess` 时，是否要禁用最终生成 URL 中添加 bucket 前缀 （已废弃，请使用 outputURLPattern） | 默认为 `false` |
#### 通用占位符 Payload
_上传路径_ 和 _自定义输出 URL 模板_ 支持的通用占位符，插件将会自行用变量替换到实际使用的路径中。
| payload | 描述 |
| --------------- | ------------------- |
| `{year}` | 当前日期 - 年 |
| `{month}` | 当前日期 - 月 |
| `{day}` | 当前日期 - 日 |
| `{hour}` | 当前日期 - 时 |
| `{minute}` | 当前日期 - 分 |
| `{second}` | 当前日期 - 秒 |
| `{millisecond}` | 当前日期 - 毫秒 |
| `{timestamp}` | Unix 时间戳 |
| `{timestampMS}` | Unix 时间戳（毫秒） |
#### 上传路径(`uploadPath`)
支持占位符方式配置，如 `{year}/{month}/{md5}.{extName}`。除以下列表外，还指出上述通用占位符。
| payload | 描述 |
| ------------ | ---------------------- |
| `{fullName}` | 完整文件名（含扩展名） |
| `{fileName}` | 文件名（不含扩展名） |
| `{extName}` | 扩展名（不含`.`） |
| `{md5}` | 图片 MD5 计算值 |
| `{sha1}` | 图片 SHA1 计算值 |
| `{sha256}` | 图片 SHA256 计算值 |
#### 自定义输出 URL 模板(`outputURLPattern`)
支持占位符方式配置，如 `{protocol}://{host}:{port}/{path}`。除以下列表外，还指出上述通用占位符。
| payload | 描述 | 例子 |
| ------------ | ------------------------------------------------------------- | --------------------------------------------------------- |
| `{protocol}` | 原上传 URL 的协议 | `http` 或 `https` |
| `{host}` | 原上传 URL 的域名，可不不使用次此变量改为其他自己的反代的域名 | `example.com` |
| `{port}` | 原上传 URL 的端口 | `80` |
| `{dir}` | 原上传 URL 的目录 | `testBucket/2024/12` |
| `{path}` | 原上传 URL 的完整路径 | `testBucket/2024/12/4aa4f41e38817e5fd38ac870f40dbc70.jpg` |
| `{fileName}` | 文件名（含扩展名） | `test.jpg` |
| `{extName}` | 扩展名（不含`.`） | `jpg` |
| `{query}` | 上传 URL 的 querystirng 部分（不含 `?` ） | `height=100&width=200` |
| `{hash}` | 上传 URL 的 hash 部分（不含 `#` ） | `abc` |
| `{bucket}` | 上传桶名 | `testBucket` |
这个配置将会替代原有的 `urlPrefix` 、`urlSuffix`、`disableBucketPrefixToURL` 的配置。
另外每个变量都支持**正则替换**
```
语法：
{payload:/pattern/reFlag,'replacement'}
```
比如配置为 `{protocol}://example.imgbed/{path:/testBucket/i,'myimage'}`，如果原URL为 `https://cluster-test-1.s3.us-east-001.example.com/testBucket/image.jpg` 则会生成 `https://example.imgbed/myimage/image.jpg`。
#### 示例 Example
```json
"aws-s3": {
"accessKeyID": "xxx",
"secretAccessKey": "xxxxx",
"bucketName": "my-bucket",
"uploadPath": "{year}/{md5}.{extName}",
"endpoint": "s3.us-west-000.backblazeb2.com",
"outputURLPattern": "{protocol}://{host}/{path}"
}
```
如果 PicGo 像以上配置，执行上传：`picgo upload sample.png`，则最终得到图片地址为：`https://img.example.com/2021/4aa4f41e38817e5fd38ac870f40dbc70.jpg`
## 发布 Publish
With the following command, a versioned commit which modifies the `version` of `package.json` would be genereated and pushed to the origin. Github Action will automatically compile this pacakage and publish it to NPM.
```sh
npm run patch
npm run minor
npm run major
```
## 贡献 Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
## 许可证 License
Released under the [MIT License](https://github.com/wayjam/picgo-plugin-s3/blob/master/LICENSE).