客户说文档里的截图还是旧的，我重传了三遍才发现：我一直在“新增”而不是“覆盖”

前阵子给一个客户更新产品使用说明书，界面前前后后改了五版。我这边改得挺利索，截图也重新传了，结果客户回了一句：“你文档里的图，怎么还是老界面？”

我当时第一反应是不可能，明明图都重传过了。结果打开文档一个个对，才发现问题出在一个我一直想当然的地方。这个坑挺隐蔽的，记下来，省得以后再踩。

一、我以为重传就是更新，其实只是新增

我先打开那张“明明换过”的图，复制文档里的链接，用无痕窗口打开——果然是旧界面。再去上传记录里翻最新传的那张，点开来又是新界面。两张图内容不一样，链接也不一样。

也就是说，我每改一版截图就重新上传一次，服务端每次都给我生成了一个新链接，而文档里引用的，始终是最早的那条。我所谓的“更新图片”，在服务端看来根本是在不停新增文件。

后来搞懂了原理：很多图床为了避免重名冲突、让链接不被轻易猜出来，默认会给每个文件安排一条多级目录加随机路径，你本地文件都叫 overview.png，传上去之后的文件名却是一串随机字符。所以同名文件传十次，就是十条不同的链接，互不覆盖。

想通这一点我才明白，我不是图没传上去，是传上去的新图根本没人引用。

二、文件夹里躺着一堆“最终版”

顺着这个问题往回翻，我发现自己以前的命名习惯也是一场灾难。本地目录里是这样的：

• 控制台首页-v2.png
• 控制台首页-最终版.png
• 控制台首页-真的最终版.png
• 控制台首页-打死不改版.png

每改一版就起一个新名字，文档里的引用就得跟着换一遍。最麻烦的是已经随邮件发出去的那批文档——链接写死在里面，你本地改得再勤快，对方打开看到的还是发出去那一刻的旧图，救都救不回来。

那段时间我特别羡慕一种状态：链接永远不变，只让链接背后的内容更新。 后来才知道，这就是“同名覆盖”。

三、同名覆盖，其实就两个条件

要让重传等于覆盖，条件很简单：

1. 传到同一个目录；
2. 用同一个文件名，大小写都得一样。

服务端是按“目录 + 文件名”找对象的，这两个完全一致，新文件才会把旧对象顶替掉，访问链接一个字符都不变。链接不变，那所有引用它的文档、Wiki、网页，就会一起显示新内容，不用我再逐个去改。

我把随机路径和同名覆盖的区别简单列了一下：

做法	链接变化	文档里的旧引用
默认随机路径（反复重传）	每次都变	一直指向旧图
同名覆盖	始终不变	自动更新成新图

四、我重新定了规矩：名字描述位置，不描述版本

想明白之后，我把配图流程整个改了。核心就一条：文件名只描述“这是哪个位置的图”，绝不描述“这是第几版”。

具体是这么做的：

1. 按产品和模块建多级目录，比如 docs/console/，每张图用语义名，像 overview.png、menu.png，从第一版就固定下来；
2. 界面改了，就把新截图覆盖到同名文件上，不再起 v2、final 这种名字；
3. 覆盖完把新链接和文档里的旧链接逐字符对一遍，确认一模一样；
4. 链接一样，Markdown 里的引用就不用动，最后开无痕窗口直开链接，确认看到的是新图；
5. 覆盖之前，把上一版的本地源文件丢进一个按日期命名的备份目录，留个退路。

截图到粘贴这一步我早就压成了两个动作，之前写过一篇 一篇教程要截三十多张图，我把截图传图压成了截图、粘贴两个动作。配上同名覆盖之后，改一张图就是“截图、覆盖、无痕刷新”，正文一个字都不用改。

五、客户还说旧图，这次赖上了缓存

流程改完以为天下太平，结果第二天客户又说有张图没更新。我去后台一看，文件确实是新的、链接也没变。那问题就只剩一个可能：缓存。

我用命令行看了一下响应头：

curl -I https://<你的图片域名>/docs/console/overview.png

几个字段能帮你判断：

• Cache-Control 里的 max-age，决定浏览器和 CDN 边缘能缓存多久；
• ETag、Last-Modified 是内容的版本标记，内容变了它们一般也会变；
• Age 是这张副本在边缘节点缓存了多少秒。

排查顺序我也摸出来了：先开无痕窗口，无痕正常就是自己浏览器强缓存，强刷一下即可；无痕还是旧的，多半是 CDN 边缘缓存没到期，等几分钟或在服务端刷新；换个网络（比如手机热点）就正常，那是中间代理的缓存；哪儿看都是旧的，才需要回头确认是不是覆盖错了文件。

想立刻绕过缓存确认源文件，临时在链接后面加个 ?v=check 重新回源就行，确认完记得删掉。

六、也不是什么情况都敢覆盖

用顺手之后我反而提醒自己，同名覆盖不能滥用。有两种情况我会保留新版本号而不是覆盖：

• 需要新旧界面对比的时候，旧图是证据，覆盖了就找不回来了，另存一个新文件名；
• 已经随邮件、归档 PDF 发出去的图，对方那份要能还原当时的样子，我会保留原文件、把新图另传。

所以我现在的习惯是“两手抓”：在线靠同名覆盖保证链接稳定，本地靠按日期备份保证能回滚。 我自己图源放在图床小镇，同名覆盖后链接不变、多级目录归类、缓存也能自己刷新，用得比较省心；但说白了这套做法不绑定某一家，自建对象存储套上 CDN，或者任意支持同名覆盖的图床都能做，关键还是命名规矩和“该覆盖还是该新建”的判断。

我平时用 Typora 写作，截图粘贴和覆盖是打通的，配置过程在 用 Typora 写博客三年，插图终于从五步法变成了一次粘贴 里。

最后三句话总结：

• 文件名描述位置，别描述版本；
• 改界面用同名覆盖，要留历史就起新名；
• 覆盖后还是旧图，先查缓存，别赖覆盖。

官网：https://imgbed.cn