云存储上传失败对前台的影响：异常捕获与静默降级

云存储一挂，用户那边往往不是"报个错"那么简单，而是图片转圈、帖子发不出去、附件买了打不开。学完这篇，你能分清云存储上传失败在前台的几种表现，并用异常捕获 + 静默降级把"整站发不了图"压回"最差也只是存到本地"。

第一步：先认清前台会怎么坏

云存储（OSS/COS/S3 一类）出问题，前台通常有四种坏法：

1. 上传按钮一直转圈，最后弹"上传失败"，用户不知道是网络还是网站问题；
2. 帖子发出去了，但图片是裂图——文件根本没落地，库里有 URL；
3. 付费附件买了打不开，云上的签名地址过期或 Bucket 权限变了；
4. 严重时请求超时拖到 30 秒，编辑页直接白屏，用户以为整站崩了。

注意：排查时别拿管理员账号下结论。图片上传与表情包是会员专属权益，管理员豁免；管理员测着正常，普通用户那边照样失败。

第二步：后台先做零成本确认

进后台「系统设置→云存储」，核对密钥、区域、Bucket、自定义域名（建议带 https:// 与主域名，避免 www 与裸域混用）是否填错。

再进「系统设置→上传」，注意这里是两个独立字段：「允许的扩展名」管图片，「附件允许的扩展名」管附件，缺哪个格式就补哪个。

最后确认 PHP 的 upload_max_filesize / post_max_size 大于文件体积（宝塔默认 2M，手机照片常超，建议 30M+），以及 uploads 目录可写。手动传一个几十 KB 的 png 试一次，能传说明链路本身没问题。

第三步：把异常捕获补上

云 SDK 抛出的通常是 SDK 自己的异常类，网络层还可能以 warning 的形式混进来。做法是三件事：

• 用 try { ... } catch (\Throwable $e) { ... } 包住上传调用，别只 catch Exception，否则 Error 直接穿透成 500；
• 给 SDK 设连接与读取超时（3~5 秒量级），别让请求干等；
• 失败时把具体原因（超时、签名失败、权限拒绝）写进日志，前台只给一句人话提示。

上传成功后，建议把结果落到记录的 storage 字段里，标明 local 还是 cloud——后面渲染和排查都靠它。

注意：日志里别写完整密钥和带签名的 URL。这些等于临时凭证，泄露出去比上传失败严重得多。

第四步：设计三档静默降级

"静默"不等于"什么都吞掉"，而是把可控的失败悄悄兜住：

第一档：云失败 → 立刻回退本地 uploads 目录。 用户无感，只在日志留一条。这是最该先做的一档，能消掉八成投诉。

第二档：本地也失败 → 切网盘链接模式附件。 填链接 + 提取码，不占服务器存储，帖子照样能发出去。

第三档：整条链路不可用 → 关掉图片上传入口。 保留纯文本 + Markdown 发布，保证"发帖"这个核心动作不断。

注意：涉及钱的动作不能静默降级。付费附件、悬赏托管这类，失败必须明确报错，宁可让用户重试，也不能"看起来成功了"。

第五步：前台展示层配合

编辑器已有 CSRF token 自动重试机制，拉新 token 重发一次；若仍报"页面已过期"，刷新即可，同时检查后台「基本设置」的站点地址是否规范。

已发布内容里的裂图，渲染时按 storage 字段决定回源路径：云挂了走本地，本地也没有就上占位图，别留一个破图标。

第六步：验证与回滚

模拟一次故障最直接：故意把密钥改错，然后发一条带图帖，看文件有没有落到 uploads、日志有没有记录、前台有没有崩。

改完配置保存即生效，一般不用清缓存；如果改过模板，去「系统工具→缓存清理」点一下。覆盖上传新版本文件后，记得跑一次「系统工具→数据库升级」。

误删的内容别慌，前台删除是软删除，后台「内容管理→帖子管理→状态筛选→回收站」可恢复，默认保留 30 天。

小结

• 云存储失败在前台有四种表现，先分清是"上传失败"还是"裂图/买不到附件"，两者排查路径不同。
• 后台「系统设置→云存储」与「系统设置→上传」是首要排查点，扩展名是两个独立字段。
• 异常捕获要 catch Throwable、设超时、写日志，日志里去掉密钥与签名 URL。
• 静默降级分三档：回退本地 → 网盘链接模式 → 关闭上传入口；涉及交易的环节不降级。
• 用故意填错密钥的方式做故障演练，改完配置保存即生效。