WP S3 Sync

WordPress 媒体库与 S3 兼容对象存储同步插件。支持 AWS S3、MinIO、Backblaze B2、Cloudflare R2 等所有 S3 兼容服务。

功能

三种上传模式
- 同步模式 — 上传到 S3 并保留本地副本
- 转移模式 — 上传到 S3 后删除本地文件，节省服务器空间
- 直传模式 — 文件经服务器中转上传到 S3，不保留本地副本
自动上传 — 通过媒体库上传的文件自动同步到 S3，包括所有缩略图尺寸
删除同步 — 可选，从 WordPress 删除媒体时同时从 S3 删除
URL 重写 — 已上传到 S3 的附件自动使用 S3 或自定义 CDN 域名的 URL
批量迁移 — 一键将已有媒体文件批量迁移到 S3，带进度条和日志
连接测试 — 设置页面一键测试 S3 连接是否正常
零依赖 — 纯 PHP cURL 实现 AWS Signature V4 签名，无需 Composer 或 AWS SDK

环境要求

WordPress 5.0+
PHP 7.2+
PHP cURL 扩展
S3 兼容的对象存储服务

安装

将 wp-s3-sync 文件夹上传到 wp-content/plugins/ 目录
在 WordPress 后台「插件」页面启用插件
进入「设置 > S3 存储同步」填写配置

配置

S3 连接配置

配置项	说明	示例
S3 端点 URL	存储服务的 API 端点	`https://s3.us-east-005.backblazeb2.com`
区域	S3 区域标识	`us-east-1`
存储桶名称	Bucket 名称	`my-bucket`
Access Key	访问密钥 ID	—
Secret Key	访问密钥 Secret	—
路径风格访问	使用 Path-Style URL（MinIO 必选）	默认开启
本地调试模式	跳过 SSL 证书验证，仅限开发环境	默认关闭

上传与同步配置

配置项	说明
上传模式	sync（同步）/ offload（转移）/ direct（直传）
删除同步	从 WordPress 删除时是否同时删除 S3 文件
自定义 CDN 域名	用于替换 S3 URL 的 CDN 域名，如 `https://cdn.example.com`
S3 路径前缀	S3 中的存储路径前缀，默认 `wp-content/uploads`

通过 wp-config.php 配置

敏感信息可通过常量定义，优先级高于数据库配置：

define( 'WP_S3_SYNC_ENDPOINT',   'https://s3.us-east-005.backblazeb2.com' );
define( 'WP_S3_SYNC_REGION',     'us-east-005' );
define( 'WP_S3_SYNC_BUCKET',     'my-bucket' );
define( 'WP_S3_SYNC_ACCESS_KEY', 'your-access-key' );
define( 'WP_S3_SYNC_SECRET_KEY', 'your-secret-key' );

各服务商配置示例

AWS S3

配置项	值
端点	`https://s3.amazonaws.com`
区域	`us-east-1`（按实际区域填写）
路径风格	可关闭

MinIO

配置项	值
端点	`https://minio.example.com:9000`
区域	`us-east-1`
路径风格	必须开启

Backblaze B2

配置项	值
端点	`https://s3.us-east-005.backblazeb2.com`
区域	`us-east-005`（按实际区域填写）
路径风格	开启

Cloudflare R2

配置项	值
端点	`https://<account-id>.r2.cloudflarestorage.com`
区域	`auto`
路径风格	开启

上传模式说明

同步模式（sync）

文件同时存在于本地和 S3。适合需要本地备份或本地处理文件的场景。

转移模式（offload）

文件上传到 S3 后删除本地副本。适合节省服务器磁盘空间。只有确认 S3 上传成功后才会删除本地文件。

直传模式（direct）

文件通过服务器内存中转到 S3，不在本地 uploads 目录保留文件。图片文件会临时写入本地用于生成缩略图，生成后立即删除。适合不想在服务器保留任何媒体文件的场景。

批量迁移

进入「媒体 > 批量迁移到 S3」页面，可将已有的媒体文件迁移到 S3：

页面显示总文件数、已上传数、待处理数
点击「开始迁移」逐个处理
实时显示进度条和处理日志
可随时点击「停止」中断

文件结构

wp-s3-sync/
├── wp-s3-sync.php                         # 插件入口
├── includes/
│   ├── class-wp-s3-sync.php               # 主类（单例）
│   ├── class-wp-s3-sync-settings.php      # 设置页面
│   ├── class-wp-s3-sync-s3-client.php     # S3 客户端（AWS Sig V4）
│   ├── class-wp-s3-sync-uploader.php      # 上传/删除钩子
│   ├── class-wp-s3-sync-url-rewriter.php  # URL 重写
│   └── class-wp-s3-sync-bulk-handler.php  # 批量迁移
├── assets/
│   ├── css/admin.css                      # 管理界面样式
│   └── js/
│       ├── admin.js                       # 批量迁移 JS
│       └── direct-upload.js              # 直传模式 JS
└── languages/                             # 翻译文件

常见问题

连接测试失败

检查端点 URL、Access Key、Secret Key 是否正确
确认存储桶已创建且凭证有访问权限
本地开发环境无 SSL 时，开启「本地调试模式」跳过证书验证

上传后图片无法显示

检查存储桶的访问策略是否允许公开读取
如使用 CDN 域名，确认 CDN 已正确指向 S3 存储桶
检查 S3 路径前缀是否与存储桶中的实际路径一致

转移模式下本地文件未删除

只有 S3 上传成功后才会删除本地文件
检查管理后台是否有上传错误提示

许可证

GPL v2 or later

By 浪子 On 2026年5月26日

WordPress S3插件wp-s3-sync