阿里云OSS+CDN自动添加文章图片水印配置指南

一、环境准备

1. 资源清单
   • 阿里云OSS Bucket（绑定自定义域名 static.example.com）
   • 阿里云CDN加速域名，回源为Bucket的域名

二、OSS水印样式配置

1. 创建图片处理样式

   • 登录 OSS控制台 → 目标Bucket → 数据处理 → 图片处理 → 样式管理
     
   • 新建样式，我的规则名称填的是shuiyin
     

2. 权限验证

   • 确保OSS Bucket为公共读或已配置CDN鉴权回源。

---

三、CDN关键配置

1. 保留URL参数

   • 进入 CDN控制台 → 目标域名 static.example.com → 缓存配置
   • 选择 保留所有参数，确保 x-oss-process 传递到OSS。
   • 这里默认就可以，不用改
     

2. 刷新缓存

   • 在 刷新预热 中提交目录刷新：

     https://static.example.com/usr/uploads/
     

四、Handsome主题自动化配置

1. 开启镜像存储

   • 进入主题后台 → 外观设置 → 图片设置 → 本地图片云存储(镜像)加速
   • 填写OSS域名：https://static.example.com

2. 追加水印参数（仅文章图片）

   • 在同一页面找到 云存储文章图片处理后缀，输入：

     ?x-oss-process=style/shuiyin
     

     

   • 效果示例：

     原始路径：/usr/uploads/2024/article.jpg  
     转换后：https://static.example.com/usr/uploads/2024/article.jpg?x-oss-process=style/shuiyin
     

   • 很可惜，第二步这个方法行不通，我找了好几个小时的bug才解决，可能是这个后缀处理没有适配阿里云

3. 在AliOssForTypecho插件中设置

   • 这个办法亲测可以
   • 在插件中设置自定义后缀
     

4. 自动排除相册图片水印

   • 若把相册图片路径改为 /usr/uploads/gallery/，在主题的 functions.php 中添加以下代码：

     function apply_oss_watermark($content) {
         // 匹配非相册图片
         $pattern = '/https?:\/\/static\.example\.com\/((?!usr\/uploads\/gallery\/).+?\.(jpg|png|webp))/i';
         $replacement = '$1?x-oss-process=style/shuiyin';
         return preg_replace($pattern, $replacement, $content);
     }
     add_filter('content', 'apply_oss_watermark');
     

   • 此代码会跳过 /usr/uploads/gallery/ 路径的图片。

5. 手动排除相册图片水印
   

五、水印效果验证

1. 普通图片验证

   • 访问文章页面，右键检查图片URL是否包含 ?x-oss-process=style/shuiyin。
   • 使用命令行工具测试：

     curl -I "https://static.example/usr/uploads/article.jpg?x-oss-process=style/shuiyin"
     

2. 相册图片验证

   • 访问相册页面，检查图片URL是否无水印参数，例如：

     https://static.example.com/usr/uploads/gallery/photo.jpg
     

六、常见问题排查

1. 水印不显示

   • 原因1：CDN未保留参数 → 检查缓存键配置是否为“保留所有参数”。
   • 原因2：OSS样式未生效 → 通过OSS控制台「样式管理」预览测试。
   • 原因3：正则匹配错误 → 检查代码中相册路径排除逻辑。

2. CDN缓存异常

   • 手动刷新缓存 → CDN控制台 → 刷新预热 → 提交图片URL或目录。
   • 检查响应头 X-Cache: MISS 确认回源状态。

通过本教程，你的博客将实现文章图片自动添加水印，同时保持相册图片原图效果。

---

作者：xuan
个人博客：https://blog.ybyq.wang
欢迎访问我的博客，获取更多技术文章和教程。