开源一款云对象存储Typecho插件

一款用于将图片、附件等静态资源存储到腾讯云COS的 Typecho 插件，可降低本地存储负载，配合CDN加速提升访问体验。支持上传目录自定义、图片自动转 WebP/AVIF（多引擎回退）、本地路径同步、运行状态健康检查等实用功能。

插件名称：TECloudAttach（腾讯云对象存储插件 For Typecho）
插件版本：v1.4.0（2026-09-07 更新）
适用环境：Typecho 1.3.0+ / PHP 8.0+（推荐 8.2+）
开源许可：GPL-2.0
项目地址：GitHub 主仓库 / Gitee 备用镜像
发布地址：https://muzihome.com/archives/252.html
更新日志：https://github.com/muzihome/TECloudAttach/blob/main/CHANGELOG.md

一、这个插件解决什么问题？

Typecho 默认把图片、附件存在服务器本地 /usr/uploads 目录。随着文章越写越多，会面临三个痛点：

• 磁盘吃紧：2G 的小主机塞几张高清图就满了；
• 加载缓慢：单机带宽有限，图片一多页面加载就慢；
• 备份困难：换服务器/重装系统时，附件迁移费时费力。

把静态资源托管到腾讯云 COS（Cloud Object Storage），本地只留数据库和程序，图片走云存储 + CDN 分发，以上问题一次解决。

二、核心功能一览

1. 文件全生命周期同步

• 上传：图片、附件自动上传至 COS 存储桶，并自动设置公有读权限与长缓存头（Cache-Control: max-age=31536000, immutable），浏览器强缓存一年，回访秒开；
• 修改：后台替换已上传附件时，COS 内对应文件同步覆盖更新；
• 删除：删除附件时可选同步删除 COS 文件（含 WebP/AVIF 衍生文件，内置重试机制），不留垃圾对象；
• 自动回退：COS 未配置或连接失败时，自动回退到 Typecho 原生本地存储，后台文件管理不中断——云挂了也不影响你发文章。

2. WebP 自动转换（三引擎回退）

开启后，上传 jpg/png 等图片时自动转换为 WebP 并连同原图一起上传，编辑器直接返回 WebP 链接，同样的画质体积平均可缩小 30% 以上：

• 三引擎智能降级：优先 GD 库 imagewebp()；GD 不支持的格式（如 TIFF）自动回退到 Imagick 扩展（不依赖 exec）；两者均不可用时回退到 cwebp 命令行工具（需 exec 可用），三者都不可用则跳过转换只传原图，绝不报错中断；
• 三端同步：上传、修改、删除均同步处理 WebP 衍生文件，删除附件时自动清理对应 .webp（不依赖 WebP 功能开关，避免残留）；
• 安全保护：超过 5000 万像素的超大图片自动跳过（防内存溢出），GIF 动图自动跳过（防丢失动画）；
• 可配置：转换质量（默认 80，推荐 75-85）与转换格式列表（默认 jpg,jpeg,png,avif,tiff,tif）自由调整。

3. AVIF 自动转换（三级回退 + 浏览器兼容回退）

v1.4.0 新增 AVIF 格式支持。AVIF 是基于 AV1 视频编码的新一代图片格式，同等画质下文件体积比 WebP 更小（约小 20-30%）。

• 三级回退转换引擎：

  1. GD 原生编码（优先）：imageavif() 可用且 GD 支持源格式解码（jpeg/png/bmp/webp）时，直接用 GD 解码 + 编码，纯 PHP 无额外依赖；
  2. 混合解码模式（v1.4.0 新增）：GD 支持 AVIF 编码但不支持源格式解码（如 TIFF）且 Imagick 已加载时，用 Imagick 解码源文件为临时 PNG，再交 GD 编码为 AVIF。解决了 GD 不支持 TIFF 解码、Imagick 未编译 libheif 环境下的能力错位问题，无需额外安装 libheif；
  3. Imagick 原生编码（后备）：Imagick 扩展编译启用 libheif 时，直接用 Imagick 解码 + 编码；
• 浏览器兼容性回退（组合方案）：服务器端通过 HTTP Accept 头检测浏览器是否支持 AVIF，不支持时自动回退到 WebP；前端内联 JS 在 WebP 加载失败时进一步回退到原图，确保老旧浏览器也能正常显示；
• 返回路径优先级：AVIF > WebP > 原图，附件记录直接存储最优格式路径，编辑器自动返回对应格式链接；
• 三端同步：上传、修改、删除均同步处理 AVIF 衍生文件（含原图↔AVIF↔WebP 双向清理）；
• 可配置：转换质量（默认 50，推荐 40-60）与转换格式列表（默认 jpg,jpeg,png,webp,tiff,tif）自由调整。

4. 目录结构自定义

通过 {year} / {month} / {day} / {type} / {ext} 五个变量，自由组合文件在 COS 中的存放路径，例如：

其中 {type} 会自动把文件分为 images / videos / audios / documents / code / archives / fonts / other 八大类，覆盖 100+ 常见扩展名。

5. 三种域名模式，永久无签名链接

• 默认 COS 域名：开箱即用，无需任何额外配置；
• 自定义源站域名：绑定自己的域名直达 COS；
• CDN 加速域名（推荐）：腾讯云 CDN + COS 源站，全国节点加速。

所有访问 URL 均为静态无签名链接，永不过期，文章里存的就是最终链接，不会出现链接过期 403 的问题。配合 CDN 的 Referer 防盗链白名单即可满足绝大多数博客需求。

6. 运行状态 / 健康检查

配置面板内置「运行状态」Tab，无需登录服务器即可实时排查问题：

• 运行环境：插件版本、PHP 版本、COS SDK 版本、phar/curl 扩展状态；
• 图片处理：GD 版本、WebP 转换支持与引擎、AVIF 转换支持及 imageavif()/imagecreatefromavif() 函数可用性、Imagick 扩展状态、cwebp 安装状态/版本/路径、exec() 函数可用性；
• COS 配置：存储桶、地域、对象存储路径、目录结构、本地存储路径、各功能开关状态；
• 最近一次上传结果：时间、成功/失败、消息、详细参数（模式、文件名、路径、大小、WebP/AVIF 转换状态、存储桶）。

WebP 不支持时还会自动诊断原因并给出解决方案（GD 未编译 WebP / exec 被禁用 / cwebp 未安装），照着提示装就行。

三、快速上手（三步搞定）

第 1 步：创建存储桶

1. 登录腾讯云 COS 控制台 → 创建存储桶；
2. 名称格式 BucketName-AppId（如 typecho-1300000000）；
3. 所属地域建议与服务器同地域（减少回源延迟）；
4. 访问权限选「公有读私有写」（博客图片是公开内容，任何人可读、仅授权账号可写）。

第 2 步：获取 API 密钥

进入 CAM 访问管理 创建子账号（安全起见不要用主账号），关联 QcloudCOSDataFullControl 策略，或按最小权限模板配置，获取 SecretId / SecretKey（SecretKey 仅显示一次，请妥善保存）。

第 3 步：安装并配置

1. 将 TECloudAttach/ 文件夹上传至 /usr/plugins/ 目录；
2. 后台「控制台 → 插件」启用，点击「设置」；
3. 填写必填四项：SecretId、SecretKey、所属地域、存储桶名称；
4. （可选）调整对象存储路径（留空使用 COS 根目录）、上传目录结构、本地存储路径（默认 usr/uploads）；
5. （可选）在「高级配置」中配置访问域名、请求超时、WebP 转换、AVIF 转换、本地备份等；
6. 保存时插件会自动校验存储桶连通性与本地路径可写性，异常会以黄色警告条提示；
7. 切换到「运行状态」确认健康检查全部通过，即可开始使用。

提示：SecretKey 使用密码框输入、页面不明文显示；建议创建子账号并授予单桶最小权限（详见项目 README 中的权限模板 JSON）。WebP/AVIF 转换功能在全新安装时会根据服务器环境自动检测并设置默认开关状态。

四、安全与健壮性设计

这个插件在"不给你添麻烦"这件事上下了不少功夫：

• 零侵入：通过 Typecho 1.3.0 原生插件钩子实现，不修改任何核心文件，禁用即恢复；
• 失败兜底：所有 COS 操作均有 try/catch，失败自动回退本地上传并记录日志，后台操作永不中断；
• 网络重试：上传、删除、WebP/AVIF 上传、衍生文件删除均内置 1 次自动重试（间隔 200ms），应对网络瞬时波动；
• 日志脱敏：错误日志自动屏蔽 SecretKey、COS 签名参数，SecretId 保留前2后1（公开标识非密钥），排查问题不留隐私隐患；
• 文件名防护：清洗危险字符、basename() 防路径穿越、点文件（.htaccess）视为无扩展名；
• 原子写文件：本地备份与文件修改采用"临时文件 + rename 原子覆盖"，异常时旧文件由原子性保证保留，杜绝数据丢失；
• 配置保存零异常：桶校验/路径校验失败仅推送警告，绝不影响页面正常跳转；
• 动态默认开关：WebP/AVIF 转换功能根据服务器环境支持情况自动设置默认值（仅全新安装生效），避免不支持环境下默认开启导致转换失败。

五、环境要求

无需 composer——COS SDK 已用 phar 打包随插件附送，上传即用。

tif/tiff 格式转换需服务器安装 php-imagick 扩展（推荐，不依赖 exec）或 cwebp 命令行工具（需 PHP exec 可用），GD 库不支持 TIFF 解码。AVIF 的 TIFF 转换可采用混合解码模式（Imagick 解码 + GD 编码），无需 Imagick 编译 libheif。

六、常见问题速查

Q：上传成功但前台图片 403？
检查存储桶权限是否为「公有读私有写」；如用 CDN，确认未开启时间戳 URL 鉴权、博客域名在 Referer 白名单中。

Q：COS 连不上会怎样？
插件自动回退本地上传，后台文件管理不中断。到「运行状态」Tab 查看健康检查与最近上传结果定位原因。

Q：启用插件前已上传的旧文件？
插件不会自动迁移旧文件，手动将 /usr/uploads 下文件按原目录结构上传到 COS 对应路径即可。

Q：WebP 转换没生效？
确认转换开关已开启、扩展名在转换列表中（默认 jpg,jpeg,png,avif,tiff,tif），并在「运行状态」查看 WebP 支持与引擎；也可运行 php -r "var_dump(gd_info()['WebP Support']);" 验证。

Q：AVIF 转换没生效？
确认转换开关已开启、扩展名在转换列表中（默认 jpg,jpeg,png,webp,tiff,tif），并在「运行状态」查看 AVIF 支持与 imageavif() 函数可用性；GIF 动图会自动跳过（避免丢失动画）。

Q：浏览器不支持 AVIF 怎么办？
插件采用双层回退：服务器端检测 Accept 头不支持 AVIF 时自动返回 WebP 路径；前端内联 JS 在 WebP 加载失败时进一步回退到原图。老旧浏览器也能正常显示。

Q：禁用插件后图片还能显示吗？
禁用插件后，附件 URL 会恢复为本地路径。如果之前开启了「在本地保存」，图片可正常显示；否则需要将 COS 文件下载回本地对应目录。

七、迭代开发计划

TECloudAttach 将持续迭代，以下是后续版本的规划方向（按优先级排序）：

v1.5.0 — 图片处理增强（计划中）

• 图片水印：支持文字水印和图片水印，可配置位置、透明度、边距，上传时自动叠加；
• 智能缩略图：上传时自动生成多尺寸缩略图（如缩略图/中图/大图），文章中按需引用，减少大图加载流量；
• 图片压缩优化：在 WebP/AVIF 转换基础上，增加原图质量压缩、尺寸上限控制（超过指定分辨率自动缩放）；
• EXIF 处理：可选保留或清除图片 EXIF 信息（保护隐私，减少文件体积）；
• 渐进式 JPEG：JPEG 图片自动转换为渐进式格式，提升大图加载体验。

v1.6.0 — 批量管理与迁移工具（计划中）

• 本地批量迁移：一键将 Typecho 本地 /usr/uploads 历史附件批量上传到 COS，自动跳过已存在文件，支持断点续传；
• COS 文件管理器：后台直接浏览 COS 存储桶文件列表，支持预览、删除、复制链接，无需登录腾讯云控制台；
• 存储桶同步：支持两个 COS 存储桶之间的文件同步（跨地域备份、迁移存储桶）；
• 批量替换文章链接：迁移完成后自动扫描并替换文章中的本地附件链接为 COS 链接；
• 迁移进度可视化：迁移过程实时显示进度、速度、成功/失败统计，失败文件可单独重试。

v1.7.0 — 多存储支持（计划中）

• 存储抽象层：重构核心代码，将 COS 特定逻辑抽象为统一存储接口，支持插拔式存储驱动；
• 阿里云 OSS：新增阿里云对象存储支持，配置方式与 COS 一致；
• 七牛云 Kodo：新增七牛云对象存储支持；
• 又拍云 USS：新增又拍云存储支持；
• 多存储桶切换：支持配置多个存储桶，按文件类型/目录自动路由到不同存储桶（如图片走 COS、视频走 OSS）。

v2.0.0 — 架构重构与生态扩展（远期规划）

• CDN 自动刷新：文件更新/删除时自动调用 CDN 刷新 API，清除缓存，无需手动操作；
• 图片处理管道：支持可配置的图片处理流水线（裁剪→水印→压缩→格式转换），灵活组合；
• REST API：提供 RESTful API 接口，支持外部系统调用上传/删除/查询，方便与其他工具集成；
• WebP/AVIF 服务端动态转换：不预生成转换文件，改为请求时按需转换并缓存，节省存储空间；
• 插件市场兼容：适配 Typecho 插件市场规范，支持一键安装/更新。

以上计划可能根据实际需求和反馈调整优先级。欢迎在 GitHub Issues 提出功能建议。

需要特别说明的是，本人并非码农，本职工作是银行从业人员，这只是多年来的业余爱好，有空突然起劲了就瞎折腾，所以无法保证迭代计划的如期开展。

写在最后

这个插件是我在 Typecho 1.3.0 + OpenResty 1.31.1.1 + PHP 8.2.33 环境上反复打磨出来的，从 v1.0.9 到 v1.4.0 经历多轮重构：WebP 链接机制、AVIF 格式支持、三级回退转换引擎、混合解码模式、浏览器兼容回退、失败回退、日志脱敏、健康检查、配置面板交互……每个细节都力求"稳"字当头——云存储是锦上添花，但绝不能因为云挂了让博客发不了文章。

如果你也在用 Typecho 且想彻底告别磁盘焦虑，欢迎下载体验。遇到问题欢迎到 GitHub Issues 反馈，也欢迎 Star 支持。