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 兼容的对象存储服务

安装

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

配置

S3 连接配置

上传与同步配置

通过 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

MinIO

Backblaze B2

Cloudflare R2

上传模式说明

同步模式（sync）

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

转移模式（offload）

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

直传模式（direct）

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

批量迁移

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

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

文件结构

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