TECloudAttach

TECloudAttach

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

下载

功能特性

核心功能

• 文件上传：将图片、附件上传至腾讯云 COS 存储桶，自动设置公有读权限与长缓存头（Cache-Control: max-age=31536000, immutable）
• 文件修改：后台替换已上传附件时，COS 存储桶内对应文件同步覆盖更新
• 文件删除：删除附件时可选择是否同步删除 COS 上的文件（含 WebP/AVIF 衍生文件，内置重试机制）
• 自动回退：COS 未配置或连接失败时，自动回退到 Typecho 原生本地存储，后台文件管理不中断
• 网络重试：COS 上传、删除、WebP 上传均内置 1 次自动重试（间隔 200ms），应对网络瞬时波动
• 连通性校验：保存配置时自动校验存储桶是否存在及本地路径可写性，校验失败在后台以黄色警告条提示用户（不阻断保存），同时写入错误日志

存储与路径

• COS 根目录支持：对象存储路径留空即使用 COS 存储桶根目录，文件按上传目录结构分子目录存放
• 本地备份：可选择在服务器本地保留一份文件副本
• 本地存储路径可配置：可自定义本地备份与回退上传的根目录（默认 usr/uploads，更安全）
• 目录结构自定义：通过 {year} / {month} / {day} / {type} / {ext} 变量自由组合存放路径
• 媒体类型自动分类：images / videos / audios / documents / code / archives / fonts / other 八类

WebP 自动转换

• 三引擎回退转换：优先使用 GD 库 imagewebp()；GD 不支持的格式（如 TIFF）自动回退到 Imagick 扩展（不依赖 exec）；两者均不可用时回退到 cwebp 命令行工具（需 exec 可用）
• 智能链接返回：转换并上传成功后，附件记录直接存储 WebP 路径，编辑器自动返回 WebP 格式链接；转换失败则存储原格式路径，确保图片可访问
• 三端同步：上传、修改、删除均同步处理 WebP 衍生文件（删除时不依赖 WebP 功能开关，避免残留）
• 安全保护：超过 5000 万像素的超大图片自动跳过（避免内存溢出），GIF 动图自动跳过（避免丢失动画）

AVIF 自动转换

• 三级回退转换：优先使用 GD 库 imageavif()（PHP 8.1+ 编译 --with-avif）；GD 支持编码但不支持源格式解码（如 TIFF）时采用混合解码模式（Imagick 解码为临时 PNG 再交 GD 编码，无需 libheif）；GD 不可用时回退到 Imagick 扩展（需编译 libheif）；AVIF 无命令行转换工具，不依赖 exec()
• 浏览器兼容性回退（组合方案）：服务器端通过 HTTP Accept 头检测浏览器是否支持 AVIF，不支持时自动回退到 WebP；前端内联 JS 在 WebP 加载失败时进一步回退到原图，确保老旧浏览器也能正常显示
• 智能链接返回：转换并上传成功后，附件记录直接存储 AVIF 路径，编辑器自动返回 AVIF 格式链接；转换失败则存储 WebP 或原格式路径，确保图片可访问
• 三端同步：上传、修改、删除均同步处理 AVIF 衍生文件（含原图↔AVIF↔WebP 双向清理）
• 格式支持：支持 jpg/jpeg/png/bmp/webp（GD 库转换）、tif/tiff（混合解码模式或 Imagick libheif，GD 不支持 TIFF 解码）；建议不要包含 gif（动图转换会丢失动画）、avif（已是目标格式）

运行状态 / 健康检查

• 运行环境展示：插件版本、PHP 版本、COS SDK 版本、phar/curl/GD 扩展状态
• 图片处理检测：GD 版本、WebP 转换支持及引擎、AVIF 转换支持及 imageavif()/imagecreatefromavif() 函数、cwebp 工具安装状态/版本/路径、exec() 函数可用性
• COS 配置状态：存储桶、地域、对象存储路径、上传目录结构、同步本地路径、本地备份、删除同步 COS、WebP 自动转换
• 最近一次上传结果：上传时间、成功/失败状态、消息、附加详情（模式、文件名、路径、大小、WebP 转换状态、存储桶）
• WebP 不支持诊断：自动分析不支持原因并给出解决方案（GD 未编译 WebP / exec 被禁用 / cwebp 未安装）

域名与访问

• 三种域名模式：默认 COS 域名、自定义源站域名、CDN 加速域名
• 永久无签名链接：所有访问 URL 均为静态无签名链接，不会过期

界面体验

• 四 Tab 配置面板：使用说明 → 基础配置 → 高级配置 → 运行状态，左侧导航切换，内容区 Grid 布局
• 下划线输入框：去除顶部/左右边框及阴影，只保留底部 1px 边框，focus 时底部边框变蓝，简洁现代
• 必填校验交互：SecretId/SecretKey/所属地域/存储桶名称未填全时，"保存设置"按钮灰色禁用，填全后恢复可点击
• WebP 子项动态显隐：转换质量、转换格式仅在勾选"上传图片自动转换 WebP"时显示，减少视觉干扰
• 宽度自适应 100%：配置面板占满 Typecho 后台可用宽度，左侧固定导航 + 右侧弹性内容区
• 响应式适配：768px 以下自动切换为单列布局，导航变为横向标签，适配移动端

安全与可维护性

• SecretKey 密码框：配置页面使用 Password 输入框，不明文显示密钥
• 日志脱敏：错误日志自动屏蔽 SecretId、SecretKey、COS 签名参数等敏感信息
• 文件名防护：清洗危险字符，basename() 防路径穿越，点文件（.htaccess）视为无扩展名
• 必填校验：基础配置中 SecretId/SecretKey/所属地域/存储桶名称为必填项，未填全时"保存设置"按钮灰色禁用
• 零侵入：通过 Typecho 1.3.0 原生插件钩子实现，不修改任何核心文件

环境要求

开源地址

https://github.com/muzihome/TECloudAttach