Clara 图片上传链路拆解：从浏览器到云存储的完整一站

学完这篇，你能完整说清 Clara 里「用户点一下选图」到「图片出现在帖子里」中间经过了哪些关卡，并且知道每一关出问题时该去后台哪个位置改。

第一步：先把链路画出来，心里有个地图

Clara 的图片上传是一条固定流水线，顺序大致是这样：

浏览器选图 → 前端预校验 → POST 到上传接口 → CSRF 校验 → 会员权益校验 → PHP 接收上限校验 → 扩展名白名单校验 → 图片二次校验 → 落本地 `uploads` 目录或转存云存储 → 返回图片地址插入编辑器。

这条链上任何一环不通过，页面都会给你一个具体的失败原因。Clara 的设计是「谁拦的就报谁」，所以排查的第一动作永远是：先看页面报的那句话，别急着翻配置。

第二步：浏览器端会先拦一道

用户在编辑器里点图片按钮选文件，前端会先做一轮粗筛——文件体积、文件类型明显不对的，这一步就不发出去了。

这一关的意义是省流量，不是安全。真正说了算的是后面的服务端白名单，所以「前端明明能选，提交却失败」是正常现象，不是 bug。

注意：手机拍照出来的图动辄 3-8MB，前端能选、后端未必收得下。真正的瓶颈在第三步。

第三步：服务端第一道坎——PHP 的接收上限

请求到达 PHP 时，最先掐住你的是 PHP 自己的两个配置：

• `upload_max_filesize`：单个上传文件的最大体积
• `post_max_size`：整个 POST 请求体的最大体积

`post_max_size` 必须大于 `upload_max_filesize`，否则文件再小也可能在进入 PHP 代码前就被丢掉。

宝塔等面板默认通常是 2M，这个值对手机照片来说几乎必然不够。建议直接调到 30M 以上，两个值一起改，改完重启 PHP。

注意：如果失败提示是「超过 PHP 上限」这类字样，那再怎么改 Clara 后台的扩展名白名单都没用——问题不在系统里，在 PHP 配置里。

这一步同时会走 CSRF 校验。Clara 全站开启 CSRF 防护，上传请求也在其中。如果页面停留太久导致 token 过期，新版编辑器内置了自动重试机制（拉取新 token 重发一次），一般无感。若仍报「页面已过期」，刷新页面重发即可。

第四步：Clara 自己的三道校验

过了 PHP 那一关，才轮到系统逻辑：

1）会员权益校验。 图片上传是会员专属权益之一。普通用户必须开通含「图片上传」权益的套餐才能发图，管理员账号豁免。后台入口在「财务运营→会员套餐」，编辑套餐时勾选这 6 项中的「图片上传」，保存即生效。

注意：新建套餐默认一项权益都不勾，很多人配完套餐发现用户还是传不了图，就是漏了这一步。相关提示会直接说「会员专属」。

2）扩展名白名单。 后台「系统设置→上传」里有两个独立字段，新手最容易搞混：

• 允许的扩展名——管图片
• 附件允许的扩展名——管附件

两者互不影响。图片传不上去，先检查第一个字段里有没有 jpg、png、webp 这些格式。

3）图片二次校验。 光看扩展名不够，Clara 还会对文件做一次真实图片校验，把改名的伪装文件挡在外面。这是上传安全基线的一部分，不提供关闭开关。

第五步：落盘还是上云

校验全过之后，文件要有个去处，取决于你是否开了云存储：

• 未开云存储：文件写进服务器本地的 `uploads` 目录，返回本站地址。
• 已开云存储：在「系统设置→云存储」里配置并开启后，链路末端切换为上传到云端对象存储，正文里写入的是云端地址。图片不占服务器磁盘，也省了带宽。

选哪种看你的实际情况：小站、图片量不大，本地目录最省事；图多、访问量大、或者服务器磁盘紧张，直接上云存储。

如果走到这一步失败，而前面都正常，八成是 `uploads` 目录不可写。去服务器把该目录权限放开即可——页面同样会明确提示「目录不可写」。

第六步：回写正文与后续管理

上传成功后，接口返回图片地址，编辑器把它插进正文对应位置。帖子发布时，地址随内容一起入库。

后续想统一管图，走后台「附件管理」。要清理历史文件也在这一块处理，别直接去服务器上删目录，容易删出死链。

注意：Clara 是保存即生效、无需清缓存的系统，改完上传相关配置直接生效，不用额外跑清理动作。系统本身也不需要 Composer、不需要命令行、没有编译缓存，上传文件即部署。

一套顺手的排查顺序

遇到图片传不上去，按这个顺序走，基本三步内定位：

1. 看页面报的具体原因；
2. 报「超过 PHP 上限」→ 改 `upload_max_filesize` / `post_max_size` 到 30M+ 并重启 PHP；
3. 报「格式不允许」→ 查「系统设置→上传」的允许的扩展名；
4. 报「会员专属」→ 查会员套餐是否勾了图片上传权益；
5. 报「目录不可写」→ 查 `uploads` 目录权限；
6. 全都对但还是失败 → 看是否开了云存储但配置有误。

小结

• 图片上传是一条链：前端预校验 → CSRF → 会员权益 → PHP 上限 → 扩展名白名单 → 图片二次校验 → 本地或云存储 → 回写正文。
• PHP 的 `upload_max_filesize` 与 `post_max_size` 是最常见的隐形瓶颈，宝塔默认 2M 要调大。
• 「允许的扩展名」和「附件允许的扩展名」是两个字段，各管各的。
• 图片上传是会员权益，套餐默认不勾，需要手动开。
• 云存储开关在「系统设置→云存储」，开了就走云端，不开走本地 `uploads`。
• 失败时先读页面提示，它通常直接告诉你是哪一关拦的。