阿里云OSS同步插件

WordPress 媒体库图片自动同步到阿里云OSS，支持本地操作与OSS双向同步。

功能特性

• ✅ 上传同步：媒体库上传图片时自动上传到OSS，保持原路径结构
• ✅ 删除同步：从媒体库删除图片时自动从OSS删除对应文件
• ✅ 缩略图同步：上传时同步所有尺寸的缩略图
• ✅ 批量同步：一键将现有媒体库全部同步到OSS
• ✅ CDN加速：可配置CDN域名，图片链接自动替换为CDN地址
• ✅ 状态记录：每张图片同步状态记录在元数据中
• ✅ 后台运行：批量同步在后台异步执行，不卡页面
• ✅ 零依赖：原生PHP HTTP实现，无需安装composer或SDK

安装步骤

1. 上传插件

上传插件目录 zuoyunlai-oss-sync/ 到 WordPress 的 wp-content/plugins/ 目录

2. 在WordPress后台激活插件

后台 → 插件 → 找到"阿里云OSS同步插件" → 启用

3. 配置OSS

1. 后台 → 设置 → OSS同步
2. 填写阿里云 AccessKey ID / Secret
3. 填写 Bucket 名称和 Endpoint
4. 保存设置（系统会自动验证连接）

4. 阿里云OSS控制台设置

CORS跨域规则（必须）：

• 对象存储 → 选择Bucket → 数据安全 → 跨域设置
• 添加规则：
  • Allowed Origin：https://www.zuoyunlai.com（你的域名）
  • Allowed Methods：GET, PUT, POST, DELETE, HEAD
  • Allowed Headers：*
  • Expose Headers：ETag
  • Max Age：3600

Bucket权限：

• 媒体文件建议设为公共读
• 如需防盗链，在"防盗链"设置中白名单你的CDN域名

5. 批量同步现有图片（可选）

在设置页面点击「立即批量同步到OSS」，将现有媒体库图片同步到OSS

配置说明

存储路径结构

OSS Bucket/
└── wp-content/uploads/           ← 前缀
    └── 2026/
        └── 05/
            ├── image.jpg            ← 原图
            ├── image-150x150.jpg     ← 缩略图
            └── image-300x200.jpg    ← 中等尺寸

CDN工作原理

用户访问图片
    ↓
WordPress输出URL: https://cdn.example.com/wp-content/uploads/2026/05/image.jpg
    ↓
CDN节点（缓存命中则直接返回）
    ↓
未命中 → 回源到OSS → 返回给用户并缓存

媒体库元数据

插件在每张图片附件中保存以下元数据：

• _zoss_sync_status：同步状态（synced / failed）
• _zoss_oss_key：OSS存储路径（如 wp-content/uploads/2026/05/image.jpg）
• _zoss_oss_url：OSS访问地址（含CDN域名）

钩子（Hooks）

// 上传到OSS前拦截（返回false则跳过本次OSS上传）
add_filter('zoss_before_upload', function($file_path, $oss_key) {
    // $file_path: 本地文件完整路径
    // $oss_key:   OSS存储路径
    return true; // return false to skip
}, 10, 2);

// 上传OSS成功后回调
add_action('zoss_upload_success', function($attachment_id, $oss_key, $oss_url) {
    // your code
}, 10, 3);

// 从OSS删除前回调
add_action('zoss_before_delete', function($oss_key) {
    // your code
}, 10, 1);

常见问题

Q: 提示"连接测试失败"？ A: 检查：1) AccessKey/Secret是否正确；2) Bucket名称是否匹配；3) Endpoint是否正确（结尾无https://）；4) 该RAM账号是否有OSS读写权限

Q: 上传成功但OSS上看不到文件？ A: 检查Bucket的Endpoint是否与实际地域匹配。如Bucket在杭州，Endpoint不能写北京：oss-cn-hangzhou.aliyuncs.com

Q: 如何确认图片已同步到OSS？ A: 查看媒体库中该图片的元数据，_zoss_sync_status 应为 synced

Q: 开启CDN后图片不显示？ A: 1) 检查CDN是否已绑定OSS Bucket；2) 检查CDN控制台的回源HOST设置；3) 检查CDN的CORS设置

文件结构

zuoyunlai-oss-sync/
├── zuoyunlai-oss-sync.php      # 主插件文件
├── composer.json                 # 依赖配置（无需composer）
├── README.md                     # 说明文档
└── includes/
    ├── class-oss-handler.php    # OSS操作类（原生HTTP）
    └── class-admin-settings.php  # 后台设置页面

技术说明

插件使用阿里云OSS REST API（兼容AWS S3签名V4），直接通过PHP cURL发送签名请求， 无需安装阿里云官方SDK，更加轻量和可靠。