七牛上传凭证过期怎么办：deadline 1 小时机制说明

学完这篇你能弄清楚七牛上传凭证里的 deadline 到底是什么、为什么"刚还能传、过一会儿就报错"，以及凭证过期后按什么顺序排查能在几分钟内恢复上传。

第一步：先确认这是不是"凭证过期"

七牛的上传接口在凭证失效时，典型表现是 HTTP 401，返回体里带 `expired token` 字样，有些 SDK 会把它包装成"上传凭证已过期""token invalid"之类的提示。所以要先分个类：

• 401 + expired token → 基本可以认定是 deadline 到了，按下面的步骤处理。
• 400 bad token / 无效凭证 → 多半是 AccessKey、SecretKey 配错，或者 bucket 名写错了，这不是"过期"，刷新一百次也没用。
• 其他 4xx / 5xx → 偏向权限、空间状态、域名配置问题，也不属于过期。

先分清这几类，别把配置错误当成过期去反复刷新页面。

第二步：deadline 是"过期时间戳"，从签发那一刻开始算 1 小时

七牛的上传凭证（upload token）里有一个 `deadline` 字段，是一个 Unix 时间戳（单位秒），不是"还剩多少秒"。服务端生成凭证时，把 `当前时间 + 3600` 写进这个字段；七牛服务端收到上传请求时，拿自己的服务器时间去比对：当前时间 > deadline，直接拒绝。

所以要记住两个关键点：

1. 倒计时从服务端生成凭证那一刻开始，不是从你点"上传"那一刻开始。
2. 比对用的是七牛服务器的时间。你本机时间不准不影响七牛判断，但会让页面上的状态显示乱掉。

注意：3600 秒（1 小时）是七牛官方文档示例里的常见写法，属于约定俗成的默认值，不是七牛强制的固定上限。真正生效的，是签发方写进 deadline 的那个数字。

第三步：三种最常踩的触发场景

• 页面开了太久才传。 打开编辑器、选好图、慢慢写了两千字正文，回头再点上传——中间可能已经过去一两个小时。凭证是页面初始化时领的，早就废了。
• 大文件传得太慢。 手机小视频、几十 MB 的压缩包，弱网下挂着传了半小时以上，中途又续传又重试，凭证早就过期了。
• 服务器时间跑偏。 服务器时区或系统时间不对，签发出来的 deadline 本身就是一个过去的时间，表现为"一上传就说凭证过期"，刷新多少遍都好不了。

第四步：按这个顺序处理

1. 刷新页面重拿凭证。 最直接有效的一步。凭证一般随页面加载或编辑器初始化时下发，刷新一次就是一次新签发，重新选文件上传即可。
2. 检查服务器时间。 在面板里看一眼系统时间和时区，跟标准时间差几分钟以上就校准（宝塔面板里有同步时间的功能）。这类问题刷新一百次都不会好。
3. 清掉旧凭证缓存。 浏览器缓存、CDN 缓存，或者系统自身的运行时缓存里如果存着旧凭证，会出现"明明刷新了还是过期"。清一次缓存再看。
4. 切本地存储做对照实验。 到后台「系统设置→云存储」把当前的云存储配置停掉，改用本地存储传一张图试试。如果本地能传、云存储报过期，说明问题出在凭证签发环节，而不是文件本身。

注意：如果你同时遇到"上传失败"，先按页面提示的具体原因走——图片和附件是「系统设置→上传」里两个独立的扩展名字段；PHP 的 `upload_max_filesize` / `post_max_size` 也要大于文件体积（宝塔默认 2M，手机照片很容易超）；上传目录还得可写。凭证过期只是众多上传失败原因里的一种，页面已经给了原因就别猜。

第五步：减少复发

• 别把上传页面挂在后台几小时再动手，写完正文立刻传图。
• 大文件优先走附件或网盘链接模式，别拿浏览器上传通道硬扛。
• 需要频繁上传的场景，用能在续传时重新申请凭证的分片上传组件，而不是全程死守同一个凭证。

小结

• deadline 是 Unix 时间戳，不是倒计时秒数，默认按签发时刻 + 3600 秒（1 小时）写入。
• 只有 401 + expired token 才是真过期；bad token 一类是配置错误，别混着处理。
• 处理顺序：刷新重拿凭证 → 校准服务器时间 → 清缓存 → 切本地存储做对照。
• 页面挂太久、大文件慢传、服务器时间跑偏，是三个最常见的诱因。