最近在给一个小产品补帮助文档，前前后后改了五六版，最让我烦的不是写字，而是里面那二十几张界面截图。界面每动一轮，截图就得重截。一开始我沿用老习惯，文件名叫 首页-v2.png、首页-final.png、首页-final-真的最终版.png，改到后面自己都分不清哪张是哪张。更麻烦的是，文档里的图片链接也得跟着一张张换，漏换一处，线上就挂着旧界面。
后来我把图床的同名覆盖用顺手了，这件小事基本被抹平：图还是那个文件名、链接还是那条链接，重新传一遍，所有引用它的地方刷新就是最新版。这篇把我踩过的坑和固定做法记一下。
一、先说痛点：文档改版，换的从来不只是一张图
我那份说明书同时存在好几个地方：仓库里的 README、文档站、发给客户的邮件，还有群里和工单里贴过的链接。用带版本号的新文件名时，有三个问题一直躲不掉：
- 引用处要逐个换。README、文档站、wiki 里同一张图可能出现三四次，改一次图就得全局搜一遍旧链接，漏一个就新旧混排。
- 已经发出去的救不回来。邮件、聊天记录、客户另存的文档里，链接指向的是旧文件名，你把仓库里的图换得再勤，客户照着老界面点，照样找不到按钮，然后回来问你。
- 本地一堆“最终版”。
final、final2、final-改、final-改2，过一个月谁也不敢删。
根因其实很简单：只要文件名一变，就是一条新链接，旧链接不会自己变成新图。
二、为什么“重新传一张”不等于更新
很多人（包括以前的我）以为图床像本地文件夹，把新图拖进去覆盖一下就完事。实际上不少图床为了避免重名冲突，上传时会给每张图分配随机路径，你两次上传同一张截图，拿到的是两个不同的 URL，旧图原封不动地还在老地址上。
要做到“原地更新”，得满足两个条件：
- 文件名稳定且不带版本号，让这张图有一个固定的“身份”；
- 图床支持同名覆盖——用同名文件再次上传时替换原文件、但链接保持不变。
这两点合起来，才是“图更新了、链接没换”。我在之前那篇截图即传的 10 秒工作流里提过一句“旧图不更新就用同名覆盖”，这篇把它单独展开讲。
三、我现在的固定操作
以说明书里一张“控制台总览”截图为例：
- 起一个稳定的语义文件名，比如
docs/console/overview.png，按章节放进多级目录，文件名里永远不写 v2、final、日期。 - 界面改版后重截，直接用
overview.png这个名字保存，覆盖本地原文件。 - 上传时把新图传到同一个目录、用同名覆盖；拿回的 URL 和上次逐字符相同。
- 文档里的 Markdown 引用一个字都不用改，
原封不动。 - 无痕窗口打开那条链接确认是新图，就算更新完成。
这样一来，仓库里、文档站里、之前发出去的邮件和工单里，只要是引用这条链接的地方，刷新后都是最新版。
四、覆盖完还是旧图？多半是缓存
同名覆盖也不是没有坑，我第一次用的时候就愣了一下：明明传成功了，页面上还是旧截图。排查下来基本都是缓存——URL 没变，浏览器和 CDN 就可能继续用缓存里的旧副本。
我的排查顺序是这样的：
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 自己浏览器看是旧图、无痕窗口是新图 | 本地浏览器缓存 | 强刷 Cmd+Shift+R，或清掉该图缓存 |
| 无痕窗口直开图片 URL 仍是旧图 | CDN 边缘节点还没回源 | 等缓存过期，或在图床/CDN 侧刷新该 URL |
| 图片直开是新图、嵌在网页里还是旧图 | 页面 HTML 或外层还有缓存 | 连页面一起强刷、重新发布文档页 |
| 个别地区新、个别地区旧 | 各边缘节点缓存到期时间不同 | 等几分钟，让各节点陆续过期 |
我一般会用 curl -I 图片地址 看一眼响应头里的 Cache-Control、ETag、Last-Modified，再配合无痕窗口直开图片 URL，判断源站到底更新没有。这个“先确认源站、再怀疑缓存”的思路，和我之前批量抢救旧博客裂图时排查 CDN 回源是一回事。
五、哪些地方该覆盖、哪些千万别覆盖
同名覆盖不是万能的，它改变的是“同一条链接背后的内容”，所以要分场景：
| 场景 | 建议 | 原因 |
|---|---|---|
| 帮助文档、说明书、README、状态页截图 | 用同名覆盖 | 希望所有已分发位置都显示最新版 |
| 要留痕、可追溯、可回滚的内容 | 用带版本号/日期的新文件名 | 覆盖后旧版不可找回，需要历史快照 |
| 报价单、合同、阶段性交付物 | 新建文件名，别覆盖 | 这类东西要的是“当时那一版”的凭据 |
| 多篇文档共用的通用图 | 放公共目录、名字带前缀 | 避免改一处误伤另一处 |
还有两个我自己踩过的注意点：
- 覆盖即生效、旧图一般找不回，所以本地（或 git 仓库）里务必留一份源文件，覆盖前确认没拿错图。
- 不同文档别图省事都叫
1.png、截图.png，用多级目录加语义命名隔开，既好找，也能防止误覆盖。
六、我的整体习惯
现在我的文档配图统一走图床，规则很简单：按章节建目录、文件名语义化且长期稳定、改版只覆盖不换名；确实需要留档的，另存一份带日期的归档目录，两者互不干扰。这套做法并不绑定某一家：自建对象存储再套一层 CDN，或者任意一个支持同名覆盖、链接不变的图床，都能落地，真正重要的是把命名规则和“覆盖还是新建”的判断固定下来。我个人图省事，长期图源放在了图床小镇，但这只是个人选择，换成满足同样条件的服务，结论完全一样。
最后小结几条：
- 文件名一变就是新链接，想“原地更新”必须同名覆盖 + 链接不变；
- 覆盖后看不到新图，先无痕直开确认源站，再处理浏览器/CDN 缓存；
- 要“处处最新”用覆盖，要“保留历史”用版本号，别用反；
- 覆盖前本地留底，目录和命名规范化，避免误覆盖。
同名覆盖、链接不变这类能力，现在不少图床和对象存储都提供，挑一个顺手、能长期用的即可，不必拘泥于具体哪一家。我自己用的那家官网在 imgbed.cn ，仅供参考，同类选择还有很多。
